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Chapter 1. About this book 


This book is a reference for programmers using IBM* Systems Application Architec- 
ture* AD/Cycie* PL/I Package/2. It is not a tutorial, but is designed for the reader 
who already has a knowledge of the language and who requires reference informa- 
tion needed to write a program that will be processed by PL/I compiler for OS/2*. It 
contains guidance information and general-use programming interfaces. 


Because this book is a reference manual, it is not intended to be read from front to 


back, and terms may be used before they are defined. Terms are shown in italics 
where they are defined in the book, and definitions are indexed. 
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row PL/i Package/2 fits in the AD/Cycle framework 


PL/I Package/2 is a participating product in the AD/Cycle framework, IBM's com- 
posite application for developing and maintaining applications in Systems Applica- 
tion Architecture* environments. The AD/Cycle framework consists of tools that 
support the full range of application development activities, plus an application 
development platform of specifications and services for integrating those tools. 
Tools that conform to these specifications and services operate in concert with 
other conforming tools. They present a common user interface, use common func- 
tions when appropriate, and share common application development information. 
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Figure 1. AD/Cycle Framework 


AD/Cycle tools are grouped according to the type of application development activ- 
ities they help perform. Figure 1 shows the AD/Cycle tool sets and their relation- 
ship to the traditional development phases. Each tool set is a collection of 
products, from IBM and members of the IBM International Alliance for the AD/Cycle 
framework. PL/I Package/2 is part of the languages tool set, indicated by the 
shaded box. PL/I Package/2 consists of a powerful new language compiler and a 
Language Environment* that work together to provide solutions for your application 
development needs. 


For more information about the AD/Cycle framework, see the publication Systems 
Application Architecture: AD/Cycle Concepts, GC26-4531. 
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Using your documentation 


The publications provided with PL/I Package/2 are designed to help you do PL/I 
programming on a personal workstation. Each publication helps you perform a dif- 
ferent task. 


Where to look for more information 
Figure 2. How to Use the Publications You Receive with PL/| Package/2 


To... Use... 

Evaluate the product PLA Package/2 Fact Sheet 

Understand warranty information PLA Package/2 Licensed Program Specifications 

Install the compiler and run-time PLA Package/2 Installation 

library 

Prepare and test your programs PLA Package/2 Programming Guide 

and get details on compiler mes- 

sages : 

Get details on PL/I syntax and PLA Package/2 Language Reference 

specifications of language ele- PLA Package/2 Reference Summary 

ments 

Get details on run-time messages PLA Package/2 Language Environment Run-Time 
Messages 


For the complete titles and order numbers of these and other related publications, 
see the “Bibliography” on page 468. 


Notation conventions used in this book 


The following sections describe how information is presented in this book. Exam- 
ples and user-supplied information are presented in mixed-case characters. 


How to read the syntax diagrams 
Throughout this book, syntax is described using the following structure: | 
* Read the syntax diagrams from left to right, from top to bottom, following the 


path of the line. The following table shows the meaning of symbols at the 
beginning and end of syntax diagram lines. . 


Symbol Indicates 

>>— the syntax diagram starts here 

——> the syntax diagram is continued on the next line 

>— the syntax diagram is continued from the previous line 
> the syntax diagram ends here 


if Required items appear on the horizontal line (the main path). 


p>—STATEMENT—requi red- 7 tem—_—_——_____—___~___—_->» « 
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Optional items appear below the main path. 


ey eee ere ee 
optional-ite 





When you can choose from two or more items, the items appear vertically, in a 
stack. If you must choose one of the items, one item of the stack appears on 
the main path. The default, if any, appears above the main path and is chosen 
by the compiler if you do not specify another choice. 


default-ite 

r>—STATEMENT—f choice 1} _______________ 
choice 2 

Note: 

1 Because choice 1 appears on the horizontal bar, one of the items must be included in 


the statement. If you don't specify either choice 1 or choice 2, the compiler implements 
the default for you. 





If choosing one of the items is optional, the entire stack appears below the 
main path. 


>>—STATEMENT. < 
[opt ional-choice 1 
optional-choice 2 


An arrow returning to the left above the main line is a repeat arrow, and it indi- 
cates an item that can be repeated. 





>>—STATEMENT—*-repeatable-ite < 





A repeat arrow above a stack indicates that you can make more than one 
choice from the stacked items, or repeat a single choice. 


If there is a comma as part of the repeat arrow, you must use a comma to 
separate items in a series. 


>» —STATEMENT—Y_repeatable-ite < 





If the comma appears below the repeat arrow line instead of on the line as 
shown in the previous example, the comma is optional as a separator of items 
in a series. 


A syntax fragment is delimited in the main syntax diagram by a set of vertical 
lines. The corresponding meaning of the fragment begins with the name of the 
fragment followed by the syntax, which starts and ends with a vertical line. 
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Semantics 


>>—STATEMENT—] fragment -K}_-——-——_-—________—__—_—_ « 


fragment: 


L—syntax  §emsAAASp$Spp$A $m 





Keywords appear in uppercase (for example, STATEMENT) They must be 
spelled exactly as shown. Variables appear in all lowercase letters (for 
example, item). They represent user-supplied names or values. 


If punctuation marks, parentheses, arithmetic operators, or other symbols are 
shown, you must enter them as part of the syntax. 


To describe the PL/I language, the following conventions are used: 


The descriptions are informal. For example, we usually write “x must be a vari- 
able” instead of the more precise “x must be the name of a variable.” Similarly, 
we may sometimes write “x is transmitted” instead of “the value of x is trans- 
mitted.” When the syntax indicates “reference,” we may later write “the variable” 
instead of “the referenced variable.” 


When we say that two different source constructs are equivalent, we mean that 
they produce the same result, and not necessarily that the implementation is 
the same. 


Unless specifically stated in the text following the syntax specification, the 
unqualified term “expression” or “reference” refers to a scalar expression. For 
an expression other than a scalar expression, the type of expression is noted. 
For example, the term “array expression” indicates that neither a scalar 
expression nor a structure expression is valid. 


When a result or behavior is undefined, it is something you “must not” do. Use 
of an undefined feature is likely to produce different results on different imple- 
mentations or releases of a PL/I product. The application program is consid- 
ered to be in error. 


Default is used to describe an alternative value, attribute, or option that is 
assumed by the system when no explicit choice is specified. 


Implicit is used to describe the action taken in the absence of an explicit spec- 
ification by the program. 


The blank symbol (6) indicates a blank character. 


Industry standards used 


The PL/I Package/2 compiler compiler is designed according to the specifications of 
the following industry standards as understood and interpreted by IBM as of 
December 1987: 


* American National Standard Code for Information Interchange (ASCIl), 


X3.4 - 1977 


* American National Standard Representation of Pocket Select Characters in 


Information Interchange, level 1, X3.77 - 1980 (proposed to ISO, March 1, 
1979) 
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* The draft proposed American National Standard Representation of Vertical Car- 
riage Positioning Characters in Information Interchange, level 1, d(pDANS X3.78 
(also proposed to ISO, March 1, 1979) 


* Selected features of the American National Standard PL/I General Purpose 
Subset (ANSI X3.74-1987). 
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Chapter 2. Program elements 


This chapter describes the basic elements that are used to write a PL/I program. 
The elements include character sets, programmer-defined identifiers, keywords, 
delimiters, and statements. 


PL/I supports the Single Byte Character Set (SBCS) and the Double Byte Character 
Set (DBCS). 


The implementation limits for PL/I's language elements are listed in the 
Appendix A, “Limits” on page 465. 


Single-byte character set 


PL/I supports the ASCII Character Set 0850, which contains the English alphabet, 
digits, special characters, and other national language and control characters. Con- 
stants and comments can contain any SBCS character value. PL/I elements (for 
example, statements, keywords and delimiters) are limited to the characters 
described in the following sections. 


Alphabetic and extralingual characters 


10 


The default alphabet for PL/I is the English alphabet plus the extralingual charac- 
ters. 


Alphabetic characters 

There are 26 base alphabetic characters that comprise the English alphabet. They 
are shown in Figure 3 with the equivalent ASCII and EBCDIC values in 
hexadecimal notation. 


Figure 3 (Page 1 of 2). Alphabetic equivalents 


EBCDIC _EBCDIC ASCII ASCII 
Uppercase Lowercase Uppercase Lowercase 

Character Hex Value Hex Value Hex Value Hex Value 

A C1 81 44 61 

B C2 82 42 62 

Cc C3 83 43 63 

D C4 84 44 64 

E C5 85 45 65 

F C6 86 46 66 

G C7 87 47 67 

H C8 88 48 68 

| C9 89 49 69 

J D1 91 4A 6A 

K D2 92 4B 6B 

L D3 93 4C 6C 

M D4 94 4D 6D 
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Decimal digits 


Decimal digits 


Figure 3 (Page 2 of 2). Alphabetic equivalents 


EBCDIC EBCDIC ASCII ASCII 
Uppercase Lowercase Uppercase Lowercase 

Character Hex Value Hex Value Hex Value Hex Value 

N D5 95 4E 6E 

O D6 96 4F 6F 

P D7 97 50 70 

Q D8 98 51 71 

R D9 99 52 72 

S E2 A2 53 73 

T E3 A3 54 74 

U E4 A4 55 75 

V E5 A5 56 76 

WwW E6 A6 57 77 

X E7 A7 58 78 

Y E8 A8 59 79 

Z E9 AQ 5A 7A 


Extralingual characters 

The default extralingual characters are the number sign (#) the at sign (@), and the 
currency sign ($). The hexadecimal values for these characters vary across code 
pages. You can use the NAMES compiler option to define your own extralingual 
characters. For more information on defining extralingual characters, refer to the 
PL/I Package/2 Programming Guide. 


Alphanumeric characters 
An alphanumeric character is either an alphabetic or extralingual character, or a 
digit. 


PL/I recognizes the 10 decimal digits, O through 9. They are also known simply as 
digits and are used to write decimal constants and other representations and 
values. The following table shows the digits and their hexadecimal values. 


Figure 4 (Page 1 of 2). Decimal digit equivalents 


EBCDIC ASCII 
Character Hex Value Hex Value 
0 FO 30 
1 F1 31 
2 F2 32 
3 F3 33 
4 F4 34 
5 F5 35 
6 F6 36 
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Binary digits 


Figure 4 (Page 2 of 2). Decimal digit equivalents 


EBCDIC ASCII 
Character Hex Value Hex Value 
7 F7 37 
8 F8 38 
9 F9 39 


Binary digits 
PL/I recognizes the 2 binary digits, 0 and 1. They are also known as bits and are 
used to write binary and bit constants. 


Hexadecimal digits 


PL/I recognizes the 16 hexadecimal digits, 0 through 9 and A through F. A through 
F represent the decimal values 10 through 15, respectively. They are also known 
as hex digits or just hex and are used to write constants in hexadecimal notation. 


Special characters 


Figure 5 shows the special characters, their PL/I meanings, and their ASCII and 
EBCDIC values in hexadecimal notation. 


Figure 5 (Page 1 of 2). Special character equivalents 


Default Default 
EBCDIC ASCII 

Character Meaning Hex Value Hex Value 

0) Blank 40 20 

= Equal sign or assignment symbol 7E 3D 

+ Plus sign 4E 2B 

- Minus sign 60 2D 

* Asterisk or multiply symbol 5C 2A 

/ Slash or divide symbol 61 2F 

( Left parenthesis 4D 28 

) Right parenthesis 5D 29 

; Comma 6B 2C 
Point or period 4B 2E 

; Single quotation mark 7D 27 

: Double quotation mark 7F 22 

% Percent 6C 25 

; Semicolon 5E 3B 
Colon 7A 3A 
Not symbol, exclusive-or symbol 

= (Note 1) 5F 5E 

& And symbol 50 26 

| Or symbol (Note 1) 4F 7C 
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Composite symbols 


Figure 5 (Page 2 of 2). Special character equivalents 


Default Default 
EBCDIC ASCIl 
Character Meaning Hex Value Hex Value 
> Greater than symbol 6E 3E 
< Less than symbol 4C 3C 
at Break character (underscore) 6D 5F 
7 Question mark 6F 3F 


Note 1: 


The or (I) and the not (—) symbols have variant code points. You can use the compiler 
options OR and NOT to define alternate symbols to represent these operators. For more 
information about defining symbols, refer to the PL/I Package/2 Programming Guide. 


Composite symbols 
You can combine special characters to create composite symbols. The following 
table describes these symbols and their meanings. Composite symbols cannot 
contain blanks. 


Figure 6. Composite symbol description 


Composite Symbol Meaning 


| Concatenation 

ial Exponentiation 

a< Not less than 

=> Not greater than 

a= Not equal to 

<= Less than or equal to 
>= Greater than or equal to 
fo . Start of a comment © 

*] End of a comment 

-—> Locator 


Case sensitivity 
You can use a combination of lowercase and uppercase characters in a PL/I 
program. 


When used in keywords or identifiers, the lowercase characters convert to the cor- 
responding uppercase characters. This is true even if you entered a lowercase 
character as a DBCS character. 


When used in a comment or in a character, mixed, or a graphic string constant, 
lowercase characters remain lowercase. 
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SBCS Statement elements 


Statement elements for SBCS 


Identifiers 


This section describes the elements that make up a PL/I program when using 
SBCS. 


A PL/I statement consists of identifiers, delimiters, operators, and constants. Con- 
stants are described in Chapter 3, “Data elements” on page 24. 


An identifier is a series of characters, not contained in a comment or a constant. 
Except for P, PIC, and PICTURE, identifiers must be preceded and followed by a 
delimiter. (P, PIC, and PICTURE identifiers can be followed by a character string.) 
The first character of an identifier must be one of the alphabetic or extralingual 
characters. Other characters, if any, can be alphabetic, extralingual, digit or the 
break (_) character. 


Identifiers can be PL/I keywords or programmer-defined names. Because PL/I can 
determine from the context if an identifier is a Keyword, you can use any identifier 
as a programmer-defined name. There are no reserved words in PL/I. 


PL/I keywords 

A keyword is an identifier that has a specific meaning in PL/I. Keywords can 
specify such things as the action to be taken or the attributes of data. For 
example, READ, DECIMAL, and ENDFILE are keywords. Some keywords can be 
abbreviated. The keywords and their abbreviations are shown in uppercase letters. 


Programmer-defined names 

In a PLA program, names are given to variables and program control data. There 
are also built-in names, condition names, and generic names. Any identifier can be 
used as aname. A name can have only one meaning in a program block. For 
example, the same name cannot be used for both a file and a floating-point vari- 
able in the same block. 


To improve readability, the break character (_) can be used in a name, such as 
Gross_Pay. 


Examples of names are: 
A Rate_of_pay 


Record Loop_3 


Additional requirements for programmer-defined external names are given in 
“INTERNAL and EXTERNAL attributes” on page 134. 


An asterisk (*) may be used as_an identifier name in situations where a name is 
required but you have no need to refer to it. 
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miters and operators 


Delimiters and operators 


Delimiters and operators are used to separate identifiers and constants. Figure 7 
shows delimiters, and Figure 8 shows operators. 


Figure 7. Delimiters 
Name Delimiter 


Comment aed | 


Comma ; 


Period 


Semicolon : 


Assignment = 
symbol 


Colon 


Blank 9) 


Parentheses () 


Locator —> 
Percent % 


Single quote 


Double quote 


Use 


The /* and */ enclose commentary (this delimiter 
includes the /* and the */ and any characters 
between them.) 


Separates elements of a list; precedes the BY NAME 
option 


Connects elements of a qualified name; decimal or 
binary point 


Terminates a statement 


Indicates assignment 


Connects prefixes to statements; connects lower- 
bound to upper-bound in a dimension attribute; used 
in RANGE specification of DEFAULT statement 


Separates elements 


Enclose lists, expressions, iteration factors, and 
repetition factors; enclose information associated 
with various keywords 


Denotes locator qualification 
Indicates % statements 


Encloses constants (indicates the beginning and end 
of a constant) 


Encloses constants (indicates the beginning and end 
of a constant) 


Note: Omitting certain symbols can cause errors that are difficult to trace. Common errors 
are unbalanced quotes, unmatched parentheses, unmatched comment delimiters, and 


missing semicolons. 


Figure 8 (Page 1 of 2). Operators 
Operator type Character(s) 


Arithmetic + 


Comparison = 


Description 


Addition or prefix plus 
Subtraction or prefix minus 
Multiplication 

Division 

Exponentiation 

Equal to 

Not equal to 

Less than 

Not less than 

Greater than 

Not greater than 

Less than or equal to 
Greater than or equal to 
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Blanks 


Figure 8 (Page 2 of 2). Operators 


Operator type Character(s) Description 
Logical a Not, Exclusive-or 
& And 
| Or 
String | Concatenation 


The characters used for delimiters can be used in other contexts. For example, the 
period is a delimiter when used in name qualification (for example, 

Weather. Temperature), but is a decimal point in an arithmetic constant (for example, 
3.14). . 


Blanks 

You can surround each operator or delimiter with blanks (6). One or more blanks 
must separate identifiers and constants that are not separated by some other 
delimiter. Any number of blanks can appear wherever one blank is allowed. 


Blanks cannot occur within identifiers, composite symbols, or constants (except in 
character, mixed, and graphic string constants). 


Some examples are: 


abt+bc is equivalent to Ab + Bc 
Table(10) is equivalent to TABLED(D10Dbb ) 
First, Second is equivalent to first, bsecond 
AtoB is not equivalent to AbtobB 


Other cases that require or allow blanks are noted where the feature of the lan- 
guage is discussed. 


Comments 

Comments are allowed wherever blanks are allowed as delimiters in a program. A 
comment is treated as a blank and used as a delimiter. Comments are ignored 
and do not affect the logic of a program. The syntax for a comment is: 





I* specifies the beginning of a comment. 


text specifies any sequences of characters except the */ composite symbol, 
which would terminate the comment. 


*/ specifies the end of the comment. 


A comment can be entered on one or more lines. For example: 
A = /* This comment is on one line */ 21; 


/* This comment spans 
two lines a 
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Statements 


Statements 


In the following example, what appears to be a comment is actually a character 
string constant because It is enciosed in quoies. 


A = '/* This is a constant, not a comment */' ; 


You use identifiers, delimiters, operators, and constants to construct PL/I state- 
ments. 


Although your source program consists of a series of records or lines, PL/I views 
the program as a continuous stream of characters. There are few restrictions in the 
format of PL/I statements, and programs can be written without considering special 
coding rules or checking to see that each statement begins in a specific column. A 
statement can begin in the next position after the previous statement, or it can be 
separated by any number of blanks. 


Some statements begin with a % symbol. These statements are either control 
statements that direct the compilation (controlling listings, including program source 
text from a library, and so on) or are PL/I Macro Facility statements. A control 
statement must be on a line by itself. 


To improve program readability and maintainability and to avoid unexpected results 
caused by loss of trailing blanks in source lines, the following recommendations 
should be followed: 


* Do not split a basic language element across lines. If a string constant must be 
written on multiple lines, use the concatenation operator (|). 


* Do not write more than one statement on a line. 
* Do not split % control statements across lines. 
The PL/I statements and the control statements are alphabetically listed in 


Chapter 8, “Statements” on page 167. The Macro Facility statements are alpha- 
betically listed in “Macro facility statements” on page 453. 


The syntax for a statement is: 


n= Agate ARE Gl shail eee * > SC 
condi tion-prefix label -prefix. statement. 





The syntax for a % statement is: 


ve ptr? 
label -prefix statement 


Every statement must be contained within some enclosing group or block. 





condition-prefix 
A condition prefix specifies the enabling or disabling of a PL/I condition. 
For more information, refer to Chapter 15, “Condition handling” on 
page 302. 


Chapter 2. Program elements 17 


Simple statements 


label-prefix 
A label prefix is one or more statement labels. It identifies a statement so 
that it can be referred to at some other point in the program. Statement 
labels are either label constants (discussed in “Label data and LABEL 
attribute” on page 46), entry constants (discussed in “Entry data” on 
page 112), or format constants (discussed in “Format data and FORMAT 
attribute” on page 47). 


Any statement, except DECLARE, DEFAULT, WHEN, OTHERWISE and 
ON statements, can have a label prefix. 


The syntax of a label prefix is: 


ee er 


The syntax for individual statements throughout this book generally does 
not show the condition prefix or the label prefix. 


statement 
A simple or a compound statement. 


Simple statements | 
The types of simple statements are: keyword, assignment, and null. 


A keyword statement is a statement that begins with a keyword. 
This keyword indicates the function of the statement. In the following example, 
READ and DECLARE are keywords: 


READ file(In) into( Input); /* keyword statement «i. 
DECLARE text char; /* keyword % statement * | 


The assignment statement contains one or more identifiers on the left side of the 
assignment symbol (=) and an expression on the right. It does not begin with a 


keyword: 
A=B+(C; /* assignment statement */ 
“size = 15; /* % assignment statement */ 


The null statement consists of only a semicolon and is a nonoperational statement: 


: /* null statement * / 
Label:; /* labeled null statement */ 
et /* % null statement */ 


Compound statements 
Compound statements are all keyword statements. Each begins with a keyword 
which indicates the function of the statement. A compound statement contains one 
or more simple or compound statements. There are four compound statements: 
IF, ON, WHEN, and OTHERWISE. A compound statement is terminated by the 
semicolon that also terminates the final statement of the compound statement. 
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Groups 


The following are examples of compound statements: 


on conversion 
onchar() = '0'; 


if Text = 'stmt' then 


do; 
select(Type) ; 
when('if') call If_stmt; 
when('do') call do_stmt; 
when('') /* do nothing */ ; 
otherwise 
call Other_stmt; 
end; 
call print; 
end; 
end; 


if type = 'AREA' %then 
“Size = size + 16; 
melSe; 


Groups 


Statements can be contained within larger program units called groups. A group is 
either a do-group or a select-group. A do-group is a sequence of statements delim- 
ited by a DO statement and a corresponding END statement. A select-group is a 
sequence of WHEN statements and an OTHERWISE statement delimited by a 
SELECT statement and a corresponding END statement. The delimiting state- 
ments are considered to be part of the group. 


When a group is used in a compound statement, control either flows into the group 
or bypasses it, effectively treating the group as if it were a single statement. 


The flow of control within a group is discussed for do-groups under “DO statement” 
on page 173 and for select-groups under “SELECT statement” on page 193. 


Every group must be contained within some enclosing group or block. Groups can 
contain none, one, or more statements or groups. 


Double-byte character set 


Each character in the double-byte character set (DBCS) is stored in 2 bytes. 
DBCS characters can be used anywhere in the source program where a comment, 
statement label, identifier, or a constant can be used. 


When the GRAPHIC compiler option is in effect, source language elements can be 
written using DBCS and SBCS. 


DBCS identifiers 


DBCS identifiers can be composed of single-byte characters in DBCS form, double- 
byte characters, or a combination of both. 
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DBCS statement elements 


Single-byte identifiers in DBCS form 

DBCS identifiers containing only single-byte characters must conform to the normal 
PL/I naming conventions, including the first-character rule. A DBCS identifier con- 
taining single-byte characters expressed as DBCS equivalents is a synonym of the 
same identifier in SBCS. 


Notes: 


1. This book uses the symbol “.” (bold period) to represent the first byte of a 
double-byte character that can also be represented as SBCS. 


2. This book uses “kk” to represent a double-byte character. 


Example: 
.1.B.M = 3; /* is the same as IBM=3; */ 


DBCS identifiers containing double-byte characters 

The sum of the number of SBCS characters plus 2 times the number of DCBS 
characters in a DBCS name cannot exceed 31. Names containing one or more 
DBCS characters are considered to be all DBCS. For example, 

AkkB 


Akk.B 
~AKkB /* are all .Akk.B (3 DBCS characters) */ 


Uses for double-byte character identifiers 

A DBCS identifier can be used wherever an SBCS identifier is allowed. When 
DBCS identifiers are used for EXTERNAL names and %INCLUDE file names, you 
must ensure that the identifiers are acceptable to the operating system, or are 
made acceptable by one of the following: 


* The EXTERNAL attribute with an environment-name is used. 
* The TITLE option of OPEN or FETCH statement is used. 


Statement elements for DBCS 


This section provides supplemental information about writing PL/I language ele- 
ments using DBCS. Definitions of the language elements in this section and 
general usage rules appear in corresponding sections in “Statement elements for 
SBCS’” on page 14. The following is a list-of the language elements, an explana- 
tion of the rules, and examples of usage. 


identifiers 
Use SBCS, DBCS or both. 
dcl Eof /* jn SBCS, is the same as */ 
dcl .E.o.f /* this in DBCS. as 
dcl kkkkx /* these are all the same, where */ 
dcl kkkk.X /* kk is a valid xf 
dcl kkkkx /* DBCS character *} 
dcl kkkk.x [* ee 
Comments 
Use SBCS, DBCS or both. | 
/* comment */ /*a 1: SBCS xf 
fe TaV pee Kk #F /* DBCS text 47 
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DBCS continuation rules 


Mixed Character String Constant 
Enclose in SBCS quotes. 


Data can be expressed in SBCS or DBCS or both. The DBCS portion is 
not converted to SBCS. 


"yasD.c'M stored as Pc ea bane 6 bytes 
1S Beis 30M stored as elBaM 3S 10 bytes 
"els BaM eM stored as Pal oe Lars) 9 bytes 
"TBMkk'M stored as IBMkk 5 bytes 
Graphic Constant 
Enclose in SBCS quotes. 
Examples: 
‘sasb.e"G /* 6 byte graphic constant */ 
Yl Ba cosa /* 10 byte graphic constant .1.B.M.'.S */ 


DBCS continuation rules 
If a DBCS character (not a DBCS semicolon) is separated from the right margin by 
a single SBCS blank, then the blank is ignored and the statement is continued at 
the left margin of the next input record. 
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This chapter introduces the kinds of data you can use in PL/I programs and the 
attributes you use to describe them. The discussion covers: 


* A review of data items 
* A review of variables and constants 
* The types of data that are available and the attributes that define them. 


For information on how to declare data, refer to Chapter 7, “Data declaration” on 
page 128. 


A data item is the value of either a variable or a constant. (These terms are not 
exactly the same as in general mathematical usage. They are discussed further in 
the next section.) Data items can be single items, called scalars, or they can be a 
collection of items called data aggregates. 


Data aggregates are groups of data items that can be referred to either collectively 
or individually. The kinds of data aggregates are arrays, structures, and unions. 
You can use any type of computational or program control data to form a data 
aggregate. 


Arrays are discussed in “Arrays” on page 144, structures in “Structures” on 
page 147, unions in “Unions” on page 149, and arrays of structures and unions 
starting in “Combinations of arrays, structures, and unions” on page 153. 


A variable has a value or values that may change during execution of a program. 
A variable is introduced by a declaration, which declares the name and certain attri- 


butes of the variable. A variable having the NONASSIGNABLE attribute is 


assumed not to change during execution. (Refer to “ASSIGNABLE and NONAS- 
SIGNABLE attributes” on page 216 for more information.) A variable reference is 
one of the following: 


* A declared variable name 

* A reference derived from a declared name through: 
— Pointer qualification 
— Structure qualification 
— Subscripting. 


(See Chapter 4, “Expressions and references” on page 50.) 


A constant has a value that cannot change. Constants for computational data are 
referred to by stating the value of the constant or naming the constant in a 
DECLARE statement. For more information on declaring named constants, see 
“Named constants” on page 45. 


Constants for program control data are referred to by name. 


© Copyright IBM Corp. 1992 


Quotation marks 


Using quotation marks 


String constants, hexadecimal constants, and the picture-specification are enclosed 
in either single or double quotation marks. 


The following rules apply to quotation marks within a string: 


° |f the included quotation marks are the same type as those used to enclose the 
string, you must enter two quotation marks (that is, '' or "") for each occur- 
rence to be included. 


° |f the included quotation marks are the type that is not used to enclose the 
string, enter only one quotation mark for each instance to be included. The 
single occurrence is treated as data. 


Examples: 
"Shakespeare''s "Hamlet"' is identical to 
"Shakespeare's ""Hamlet""" 


PICTURE "99V9" is identical to 
PICTURE '99V9' 


Note: The syntax diagrams in this book show single quotation marks. Double 
quotation marks can be substituted unless otherwise noted. 


Punctuating constants 


To improve readability, arithmetic, bit, and hexadecimal constants can use the 
break character (_ ). For example: 


"1100_1010'B is the same as '11001010'B 
1100_1010B is the same as 110010108 
"C_A'B4 is the same as "ca'b4 
"C_A'XN is the same as "ca' XN 
16_777_216 is the same as 16777216 


Data types and attributes 


Data used in a PL/I program can be classified as computational data and program 
control data: 


Computational data represents values that are used in computations to produce 
desired result. It consists of arithmetic and string data. 


Arithmetic data is either coded arithmetic data or numeric 
picture data. 


Coded arithmetic data items are rational numbers. They 
have the data attributes of base (BINARY or DECIMAL), 
scale (FLOAT or FIXED), precision (significant digits and 
decimal point placement), and mode (REAL or COMPLEX). 


Numeric picture data is numeric data that is held in character 
form and is discussed under “Numeric character data” on 
page 43. 


A string is a sequence of contiguous characters, bits, or 
graphics that are treated as a single data item. 
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Data types and attributes 


Program control data 
represents values that are used to control execution of your 
program. It consists of the data types: area, entry, label, file, 
format, pointer, and offset. 


For example: 
Area = (Radius**2) * 3.1416; 


Area and Radius are coded arithmetic variables of computational data. The 
numbers 2 and 3.1416 are coded arithmetic constants of computational data. 


If the number 3.1416 is to be used in more than one place in the program, or if it 
requires specific data or precision attributes, you should declare it as a named con- 
stant. Thus, the above statement can be coded as: 


dc] Pi FIXED DEC (5,4) VALUE(3.1416); 
area = (radius**2) * Pi; 


Constants for program control data have a value that is determined by the compiler. 
In the following example, the name loop represents a label constant of program 
control data. The value of loop is the address of the statement A=2*B;. 
loop: A=2*B; 

C=B+6; 
To work with a data item, PL/I needs to know the type of data and how to process 
it. Attributes provide this information. The kinds of attributes are: 


Data attributes 
describe both computational and program control data items. 


AREA ENTRY NONVARYING SIGNED 
BINARY FILE OFFSET STRUCTURE 
BIT FIXED PICTURE UNSIGNED 
CHARACTER FLOAT POINTER UNION 
COMPLEX FORMAT PRECISION VARYING 
DECIMAL GRAPHIC REAL 


DIMENSION LABEL RETURNS 


Descriptive attributes 
describe both computational and program control data items. They can be 
specified only in DECLARE statements (including ENTRY and GENERIC 
descriptor lists), and are the only attributes that can be specified after an 
asterisk in an ENTRY or GENERIC descriptor list. 


ALIGNED CONNECTED OPTIONAL 


ASSIGNABLE CONTROLLED UNALIGNED 
BYADDR NONASSIGNABLE 
BYVALUE NONCONNECTED 
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Non-data attributes 
describe non-data elements (for example, built-in functions) or provide 
additional description for elements that have other data attributes. They 
can be specified only in DECLARE statements (excluding ENTRY and 
GENERIC descriptor lists). 


ABNORMAL CONDITION EXTERNAL KEYED PARAMETER 
AUTOMATIC DEFINED GENERIC LIKE POSITION 
BASED DIRECT INITIAL NORMAL STATIC 
BUFFERED ENVIRONMENT INPUT OPTIONS 

BUILTIN EXCLUSIVE INTERNAL OUTPUT 


For example, the keyword CHARACTER is a data attribute for the string type of 
computational data. The keyword FILE is a data attribute for the file type of 
program control data. The INTERNAL scope attribute specifies that the data item 
is known only within its declaring block. 


The details of how you use keywords and expressions to specify the attributes are 
in Chapter 7, “Data declaration” on page 128. Briefly, they are: 


* Explicitly, using a DECLARE statement 
* Contextually, letting PL/I determine them 
° By using programmer-defined or language-specified defaults. 


Figure 9 on page 28 and Figure 10 on page 29 help you correlate PL/I' variety of 
attributes with its variety of computational and program control data types. The 
tables show that the constants and the named constants can only have the indi- 
cated data and scope attributes (Figure 9 on page 28). Variables can specify 
additional attributes (Figure 10 on page 29). 


In the example, 
Area = (Radius**2)*3.1416; 


the constant 3.1416 is given the attributes: 


DECIMAL because it is not explicitly a binary constant 

FIXED because it is fixed point number 

PRECISION(5,4) - 5 significant digits with 4 to the right of the decimal point 
REAL because it does not have an imaginary part 

INTERNAL and ALIGNED. 


(See the “Coded arithmetic” row, and “Data Attributes” and “Scope Attributes” 
columns of Figure 9 on page 28.) 


The constant 1.0 (a decimal fixed-point constant) is different from the constants 1 
(another decimal fixed-point constant), '1'B (a bit constant), '1' (a character con- 
stant), 1B (binary fixed-point constant), or 1E0 (a decimal floating-point constant). 


In the following example, the variable Pi has the programmer-defined data attri- 
butes of FIXED and DECIMAL with a PRECISION of five digits, four to the right of 
the decimal point. 


declare Pi fixed decimal(5,4) initial(3.1416); 
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Because this DECLARE statement contains no other attributes for Pi, PL/I applies 
the defaults for the remaining attributes: 


* REAL from the Data Attributes column 

® ALIGNED from the Alignment Attributes column 
* INTERNAL from the Scope Attributes column 

¢ AUTOMATIC from the Storage Attributes column 
* SIGNED from the data attributes column. 


(See the coded arithmetic row of Figure 10 on page 29.) 


Figure 9 (Page 1 of 2). Classification of attributes by constant types 


Constant Type Data Attributes Scope Attributes 
(Notes 1 and 2) (Notes 1 and 2) 
Coded REAL | imaginary internal 
arithmetic FLOAT | FIXED 
BINARY | DECIMAL 
PRECISION 
Named coded REAL | COMPLEX . internal 
arithmetic FLOAT | FIXED 


BINARY | DECIMAL 
PRECISION 

VALUE 

SIGNED | UNSIGNED 





String BIT | CHARACTER | GRAPHIC internal 
(length) 
Named string BIT | CHARACTER | GRAPHIC internal 


[(length)] 
[VARYING | NONVARYING] 
VALUE 


Named locator POINTER | OFFSET internal 
VALUE 


Named picture PICTURE interna! 
REAL | COMPLEX 
VALUE 


File(Note 4) FILE ENVIRONMENT INTERNAL | EXTERNAL 
STREAM | RECORD 
INPUT | OUTPUT | UPDATE 
SEQUENTIAL | DIRECT 





BUFFERED | UNBUFFERED(Note 5) 
KEYED 
PRINT 





Entry(Note 6) ENTRY [RETURNS] INTERNAL | EXTERNAL 
Format(Note 6) FORMAT internal 
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Figure 9 (Page 2 of 2). Classification of attributes by constant types 










Data Attributes 
(Notes 1 and 2) 


LABEL ; 





Constant Type Scope Attributes 


(Notes 1 and 2) 


Label(Note 6) 


internal 


Notes: 


1. Attributes in this table that appear in uppercase can be explicitly declared. Attributes that are in lower case are 
implicitly given to the data type. 


2. Defaults for data attributes are underlined. Because the data attributes for literal constants are contextual, 
defaults are not applicable. Named constants and file constants have selectable attributes, so defaults are shown. 


. All constants are internal. 
. File Attributes are described in Chapter 10, “Input and output” on page 228. 
. BUFFERED is the default for SEQUENTIAL files. UNBUFFERED is the default for DIRECT files. 


. Format and label constants, and INTERNAL entry constants cannot be declared in a DECLARE statement. 


oOo oa ff Ww 


Figure 10 (Page 1 of 2). Classification of attributes by variable types 


Variable Data Attributes Alignment Scope Storage Attributes 
Type Attributes Attributes 



















































Area INTERNAL | AUTOMATIC | STATIC | 
Coded REAL | COMPLEX ALIGNED | EXTERNAL een 
arithmetic FLOAT | FIXED UNALIGNED . 
(Note 1) BINARY | DECIMAL URTERNAL Is 
PRECISION mandatory for (AUTOMATIC is 
SIGNED | AUTOMATIC the default for 
TINGIGNES| BASED INTERNAL: 
DEFINED STATIC is the 
Entry ENTRY [RETURNS] PARAMETER) default for 


File FILE 
Format FORMAT 


Defined variable: 








DEFINED 
Label LABEL [POSITION] 
[(area-variable)]} PARAMETER 
Picture PICTURE ~ ALIGNED | [CONNECTED | 
REAL | COMPLEX UNALIGNED NONCONNECTED] 
[CONTROLLED] 
String BIT | CHARACTER | 
GRARING [INITIAL 
[(length)] [Cc ALL]] 
[ VARYING | 
NONVARYING] [VARIABLE] 
[NORMAL | 
ABNORMAL] 
ASSIGNABLE | 
NONASSIGNABLE 


Arrays: DIMENSION may be added to the declaration of any variable. Refer to “Arrays” on page 144 for more 
information. 
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Figure 10 (Page 2 of 2). Classification of attributes by variable types 


Variable Data Attributes Alignment Scope Storage Attributes 
Type Attributes Attributes 


Structures and unions: 





* For a major structure or union: scope, storage (except INITIAL), alignment, STRUCTURE or UNION, and the 
LIKE attributes may be specified. 

* For a member that is a structure or a union: alignment, STRUCTURE or UNION, and the LIKE attributes may be 
specified. 

* Members always have the INTERNAL scope attribute. 


Refer to “Structures” on page 147 and “Unions” on page 149 for more information. 
Notes: 


1. Undeclared names, or names declared without a data type, default to coded arithmetic variables. Default attri- 
butes are described in “Defaults for attributes” on page 141. Defaults shown are IBM defaults. ANS defaults are 
FIXED and BINARY rather than FLOAT and DECIMAL. 


2. POSITION can be used only with string overlay defining. — 


Computational data types and attributes 


This section describes the data types classified as computational data and the attri- 
butes associated with them. 


Coded arithmetic data and attributes 


Refer to “Data types and attributes” on page 25 for general information about 
coded arithmetic data. 
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BINARY and DECIMAL 


Syntax for coded arithmetic data is shown in the following diagram: 


float sequence REAL 


fixed sequence COMPLEX 
float sequence: 


[FLOAT 
Ly PRECISION for FLOAT 


DECIMAL 
PRECISION for FLOAT 


BINARY 
PRECISION for FLOAT 


fixed sequence: 


[FIXED 
Ly PRECISION for FIXED 


PRECISION for FIXED 


PRECISION for FIXED 


PRECISION for FLOAT: 


Soa remarry fa number - of - digits. \$YV$NMA A 
PRECISION 


PRECISION for FIXED: 
hee HUME AE ONE = a ey 
PRECISION ,scaling-factor. 





Figure 11. Abbreviations for coded arithmetic data attributes 


Attribute Abbreviation 
BINARY BIN 
COMPLEX CPLX 
DECIMAL DEC 
PRECISION PREC 


BINARY and DECIMAL attributes 


The base of a coded arithmetic data item is either decimal or binary. 
Default: DECIMAL. 


Refer to “PRECISION attribute” on page 32 for information about the precision- 
attribute. 


FIXED and FLOAT attributes 


The scale of a coded arithmetic data item is either fixed-point or floating-point. 

A fixed-point data item is a rational number in which the position of the decimal or 
binary point is specified, either by its appearance in a constant or by a scaling 
factor declared for a variable. 


Floating-point data items are rational numbers in the form of a fractional part and 
an exponent part. 
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PRECISION attribute 
The precision of a coded arithmetic data item includes the following factors. The 
scaling factor is used only for floating point items. 


number of digits 
is an integer that specifies how many digits the value can have. For fixed 
point items the integer is the number of significant digits. For floating point 
items the integer is number of significant digits to be maintained excluded 
the decimal point. 


scaling factor 
is an optionally-signed integer that specifies the assumed position of the 
decimal or binary point, relative to the rightmost digit of the number. If no 
scaling factor is specified, the default is 0. 


The precision attribute specification is often represented as (p,q), where p repres- 
ents the number of digits and g represents the scaling factor. 


A negative scaling factor (-q) specifies an integer, with the point assumed to be 
located q places to the right of the rightmost actual digit. A positive scaling factor 
(q) that is larger than the number of digits specifies a fraction, with the point 
assumed to be located q places to the left of the rightmost actual digit. In either 
case, intervening zeros are assumed, but they are not stored; only the specified 
number of digits is actually stored. 


If PRECISION is omitted, the precision attribute must follow, with no intervening 
attribute specifications, the scale (FIXED or FLOAT), base (DECIMAL or BINARY), 
or mode (REAL or COMPLEX) attributes at the same factoring level. 


If included, PRECISION( ) can appear anywhere in the declaration. 


Integer value means a fixed-point value with a scaling factor of zero. 


REAL and COMPLEX attributes 


The mode of an arithmetic data item (coded arithmetic or numeric character) is 
either real or complex. 


A real data item is a number that expresses a real value. 


A complex data item consists of two parts—the first a real part and the second an 
imaginary part. For a variable representing complex data items, the base, scale, 
and precision of the two parts are identical. 


Default REAL for arithmetic variables. Complex arithmetic variables must be 
explicitly declared with the COMPLEX attribute. 


An imaginary constant is written as a real constant of any type immediately fol- 
lowed by the letter |. Examples are: ° 
2/1 


3.968E101 
11011.01BI 
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SIGNED and UNSIGNED attributes 


Each of these has a real part of zero. A complex value with a nonzero real part is 
represenied vy ai expression with tie followirig syntax. 


>> real_constant a imaginary_constant-———_—__> « 
| + | res 





For example, 38+27I. 


Given two complex numbers, y and z: 


¥ 
Z 


complex(A,B); 
complex(C,D); 


x=y/z is calculated by: 


real(x) = (A*C + B*D)/(C**2 + D**2); 
jmag(x) = (B*C - A*D)/(C**2 + D**2); 


x=y*z is calculated as follows: 


A*C >> BSD; 
BAG CAND: 


real (x) 
imag(x) 


Computational conditions can be raised during these calculations. 


SIGNED and UNSIGNED attributes 

The SIGNED and UNSIGNED attributes can be used only with FIXED BINARY var- 
iables. SIGNED indicates that the variable can assume negative values. 
UNSIGNED indicates that it can assume only nonnegative values. The UNSIGNED 
attribute permits the compiler to generate more efficient code in some situations, 
such as the BY expression in a type 3 DO loop or the second argument to the 
MOD built-in function. 


SIGNED and UNSIGNED have no effect on the semantics of fixed point operations. 
All intermediate results are SIGNED. For example, the following declaration 
produces a result of SIGNED FIXED BINARY‘(8). 


dcl U7 unsigned fixed bin(7); 
Call XCU7 2 UF 2 


X is, therefore, passed a 2-byte signed integer unless the entry descriptor for X indi- 
cates otherwise. 


The built-in functions REAL and IMAG, when applied to an unsigned argument, 
have an unsigned result. All other built-ins, except UNSIGNED, have a signed 
result. 


These attributes also affect the storage requirements, as shown in Figure 12 on 
page 34 and Figure 13 on page 34. 
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Figure 12. FIXED BIN SIGNED data storage requirements 


This precision: Occupies this amount of storage: 
precision <= 7 1 
7 < precision <= 15 2 
15 < precision <= 31 4 


Figure 13. FIXED BIN UNSIGNED data storage requirements 


This precision: Occupies this amount of storage: 
precision <= 8 1 
8 < precision <= 16 2 
16 < precision <= 31 4 


Binary fixed-point data 
The data attributes for declaring binary fixed-point variables are BINARY and 
FIXED. For example: — 


declare Factor binary fixed (20,2); 


Factor is declared as a variable that can represent binary fixed-point data of 20 
data bits, two of which are to the right of the binary point. 


Refer to “SIGNED and UNSIGNED attributes” on page 33 for information on how 
much storage signed and unsigned fixed binary data occupy. 


The declared number of data bits is in the low-order positions, but the extra high- 
order bits participate in any operation performed upon the data item. Any arith- 
metic overflow into such extra high-order bit positions can be detected only if the 
SIZE condition is enabled. 


Binary fixed-point constant 

A binary fixed-point constant consists of one or more bits with an optional binary 
point, followed immediately by the letter B. Binary fixed-point constants have a pre- 
cision (p,q), where p is the total number of data bits in the constant, and q is the 
number of bits to the right of the binary point. Examples are: 


Constant Precision 
1011_0B (5,0) 
1111_1B (5,0) 
101B (3,0) 
1011.111B = (7,3) 


XN (hex) binary fixed-point constant 
The XN constant describes a REAL FIXED BINARY(31,0) constant in hexadecimal 
notation. The specified value may be 1 to 8 hexadecimal digits. The syntax is: 


ee  ————— re 
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Decimal fixed-point data 


Its hexadecimal value is the given value padded on the left with hex zeros if neces- 
sary. For exampie: 


"100'XN /* same as 'OQOOO100'XN with value 256 */ 
"8000 ' XN /* same as 'QQO008000'XN with value 32,768 */ 
"FFFF'XN /* same as 'OOOQOFFFF'XN with value 65,535 = */ 
"fFPFF_FFFF "XN /* is the value -l */ 


Decimal fixed-point data 
The data attributes for declaring decimal fixed-point variables are DECIMAL and 
FIXED. For example: 


declare A fixed decimal (5,4); 


specifies that A represents decimal fixed-point data of 5 digits, 4 of which are to the 
right of decimal point. 


These two examples: 


declare B fixed (7,0) decimal; 
declare B fixed decimal(7); 


both specify that 8 represents integers of 7 digits. 
declare C fixed (7,-2) decimal; 


specifies that C has a scaling factor of -2. This means that C holds 7 digits that 
range from -9999999*100 to 9999999*100, in increments of 100. 


declare D decimal fixed real(3,2); 


specifies that D represents fixed-point data of 3 digits, 2 of which are fractional. 


Decimal fixed-point data is stored two digits per byte, with a sign indication in the 
rightmost 4 bits of the rightmost byte. Consequently, a decimal fixed-point data 
item is always stored as an odd number of digits, even though the declaration of 
the variable may specify the number of digits, p, as an even number. 


When the declaration specifies an even number of digits, the extra digit place is in 
the high-order position, and it participates in any operation performed upon the data 
item, such as in a comparison operation. Any arithmetic overflow or assignment 
into an extra high-order digit place can be detected only if the SIZE condition is 
enabled. 


Decimal fixed-point constant 

A decimal fixed-point constant consists of one or more decimal digits with an 
optional decimal point. Decimal fixed-point constants have a precision (p,q), where 
p is the total number of digits in the constant and q is the number of digits specified 
to the right of the decimal point. Examples are: 


Constant Precision 
3.1416 (5,4) 


455.3 (4,1) 
132 (3,9) 
003 C370) 
5280 (4,0) 
0012 (4,4) 
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Binary floating-point data 
The data attributes for declaring binary floating-point variables are BINARY and 
FLOAT. For example: 


declare S binary float (16); 


S represents binary floating-point data with a precision of 16 binary digits. 


The exponent cannot exceed five decimal digits. Binary floating-point data is stored 
as IEEE normalized. If the declared precision is less than or equal to (21), short 
floating-point form is used. If the declared precision is greater than (21) and less 
than or equal to (53), long floating-point form is used. If the declared precision is 
greater than (53), extended floating-point form is used. 


Binary floating-point constant 

A binary floating-point constant is a mantissa followed by an exponent and the 
letter B. The mantissa is a binary fixed-point constant. The exponent is the letter 
E, S, D, or Q followed by an optionally-signed decimal integer (meaning 2 to the 
power of this integer). Constants using E have a precision (p) where p is the 
number of binary digits of the mantissa. Constants using S, D, and Q always have 
maximum single, double, and extended precisions respectively. Examples are: 


Constant Precision 
101101E5B (6) 
101.101E2B (6) 
11101E-28B (5) 
11.01E+42B (4) 


1S0b (21) 
1D0b (53) 
1Q0b (64) 


Decimal floating-point data 
The data attributes for declaring decimal floating-point variables are DECIMAL and 
FLOAT. For example: 


declare Light_years decimal float(5); 


in which Light_years represents decimal floating-point data of 5 decimal digits. 


Decimal floating-point data is stored as IEEE normalized. If the declared precision 
is less than or equal to (6), short floating-point form is used. If the declared preci- 
sion is greater than (6) and less than or equal to (16), long floating-point form is 
used. If the declared precision is greater than (16), extended floating-point form is 
used. 


Decimal floating-point constant 

A decimal floating-point constant is a mantissa followed by an exponent. The 
mantissa is a decimal fixed-point constant. The exponent is the letter E, S, D, or Q 
followed by an optionaily-signed decimal integer of four or less digits (meaning 10 
to the power of this integer). Constants using E have a precision (p) where p is the 
number of digits of the mantissa. Constants using S, D, and Q always represent 
single, double, and extended precision respectively. Examples are: 
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Constant Precision 
ESE=25 (2) 
15E23 (2) 
4E-3 (1) 
1.96E+07 (3) 
438E0 (3) 
3.141 593E-6 (7) 
.003_141_593E3 (9) 
1s0 (6) 
1d0 (16) 
1q0 (18) 


The last two examples represent the same value (although with different pre- 
cisions). 


String data and attributes 


Refer to “Data types and attributes” on page 25 for general information about 
strings. 


BIT, CHARACTER, and GRAPHIC attributes 
The BIT attribute specifies a bit variable. 


The CHARACTER attribute specifies a character variable. Character strings can 
also be declared using the PICTURE attribute. 


The GRAPHIC attribute specifies a graphic variable. 


The syntax for the BIT, CHARACTER, and GRAPHIC attributes is: 


et ce 
BIT WAVING > 
CHARACTER " Leerer(variablenl varvable) 
GRAPHIC 


Figure 14. Abbreviations for string data attributes 





Attribute Abbreviation 
CHARACTER CHAR 
GRAPHIC G 
NONVARYING NONVAR 
VARYING . VAR 


length specifies the length of a NONVARYING string or the maximum length of a 
VARYING string. The length is in bits, characters, or graphics (DBCS 
characters), as appropriate. 


You can specify the length as an expression or an asterisk. If the length 
is not specified, the default is 1. For named constants, length is deter- 
mined from the length of the value expression. 


For a parameter, an expression is valid only if it is CONTROLLED. An 
asterisk specification for a parameter indicates that the length is to be 
taken from the argument that is passed. 
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VARYING and NONVARYING attributes 


If the length specification is an expression, it is evaluated and converted to 
FIXED BINARY, which must be positive, when storage is allocated for the 
variable. 


For STATIC data, length must be a restricted expression. 


For BASED data, length must be a restricted expression, unless the string 
is member of a structure or a union and the REFER option is used. 


REFER See “REFER Option (Self-Defining Data)” on page 210 for the description 
of the REFER option. 


The statement below declares User as a variable that can represent character data 
with a length of 15: 


declare User character (15); 


The following example shows the declaration of a bit variable: 
declare Symptoms bit (64); 


VARYING and NONVARYING attributes 

The VARYING attribute specifies that a variable can have a length varying from 0 
to the declared maximum length. NONVARYING specifies that a variable always 
has a length equal to the declared length. 


The storage allocated for VARYING strings is 2 bytes longer than the declared 
length. The leftmost 2 bytes hold the string's current length. 


The following DECLARE statement specifies that User represents varying-length 
character data with a maximum length of 15: 


declare User character (15) varying; 


The length for User at any time is the length of the data item assigned to it at that 
time. You can determine the declared and the current length by using the 
MAXLENGTH and LENGTH built-in functions, respectively. 


PICTURE attribute 

The PICTURE attribute specifies the properties of a character data item by associ- 
ating a picture character with each position of the data item. A picture character 
specifies a category characters that can occupy that position. 


The syntax for the PICTURE attribute is: 





Abbreviation PIC 


picture-specification 
describes is either a character data item or a numeric character data item. 
Refer to “Picture characters for character data” on page 287 or “Picture 
characters for numeric character data” on page 288 for the valid charac- 
ters. 
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Character data 


An numeric picture specification specifies arithmetic attributes of numeric character 
data in much the same way that they are specified by the appearance of a con- 
stant. 


Numeric character data has an arithmetic value but is stored in character form. 
Numeric character data is converted to coded arithmetic before arithmetic oper- 
ations are performed. 


The base of a numeric character data item is decimal. Its scale is either fixed-point 
or floating-point (the K or E picture character denotes a floating-point scale). The 
precision of a numeric character data item is the number of significant digits 
(excluding the exponent in the case of floating-point). Significant digits are speci- 
fied by the picture characters for digit positions and conditional digit positions. The 
scaling factor of a numeric character data item is derived from the V or the F 
picture character or the combination of V and F. 


Only decimal data can be represented by picture characters. Complex data can be 
declared by specifying the COMPLEX attribute along with a single picture specifica- 
tion that describes either a fixed-point or a floating-point data item. 


For more information on numeric character data, see “Numeric character data” on 
page 43. 


Character data 

Data with the CHARACTER attribute can contain any of the 256 characters sup- 
ported by the character set. Data with the PICTURE attribute must have characters 
that match the picture-specification characters. Each character occupies 1 byte of 
storage. 


Character constant 
A character constant is a contiguous sequence of characters enclosed in single or 
double quotation marks. 


Quotation marks included in the constant follow the rules listed in “Using quotation 
marks” on page 25. The length of a character constant is the number of charac- 
ters between the enclosing quotation marks counting any doubled quotation marks 
as a single character. 


A null character constant is written as two quotation marks with no intervening 
blank. The syntax for a character constant is: 


AR, {ot EN 1 Aare mee ee ae ee 


character 
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Z character constant 


Examples of character constants are: 


Constant Length 
"Shakespeare's "Hamlet"' 22 
"Shakespeare's ""Hamlet""" tae 
"Page 5" 6 
'/* This is not a comment */' 2/7 
ot 0 
(2)'Walla ' 12 


In the last example, the number in parentheses is a string repetition factor, which 
indicates repetition of the characters that follow. This example is equivalent to the 
constant "Walla Walla ". The string repetition factor must be a constant and 
enclosed in parentheses. 


Z (null-terminated) character constant 
The Z constant describes a character constant that will be terminated by 
hexadecimal ‘00’. 


It is written like a character constant but with a Z suffix. The length of a Z constant 
is the same as a character constant pius 1 for the '00'x supplied by PL/I. 


A null Z constant is written as two single or double quotation marks followed by the 
Z suffix. 


The syntax is: 


thea (Se PET 
character. 





Examples of Z constants are: 


Constant Length 
"Shakespeare''s "Hamlet"'z 23 
" "7 1 


X (hex) character constant 

The X character constant is a contiguous sequence of an even number of hex 
digits enclosed in single or double quotation marks and followed immediately by the 
letter X. Each pair of hex digits represents one character. 

The length of an X constant is half the number of hex digits specified. 


A null X constant is written as two quotation marks followed by the X suffix. 


The syntax is: 


pe PL 
hex-digit hex-digit 
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Examples of X constants are: 


Constant Length 
"OdOA"x 2 
' NX , 0) 


Note: The use of X constant can limit the portability of a program. 


Bit data 
Data with the BIT attribute permits manipulation of storage in terms of bits. A col- 
lection of 8 or fewer unaligned bits occupy 1 byte of storage. 


Bit constant 

A bit constant is a contiguous sequence binary digits enclosed in single or double 
quotation marks and followed immediately by the letter B. The syntax for a bit con- 
stant is: 


ped pinary-digit- ope 


A null bit constant is written as two quotation marks, followed by B. 


Examples of bit constants are: 


Constant Length 
'1'B 1 
"1100_1010_11"B 10 
(64)'0'B 64 

1B 0 

'O'B 1 


The number in parentheses in the third example is a string repetition factor which 
specifies that the following series of bits is to be repeated the specified number of 
times. The example shown would result in a string of 64 zero bits. 


(See “Source-to-target rules” on page 77 for a discussion on the conversion of bit- 
to-character data and character-to-bit data.) 


B4 (hex) bit constant 

The Bé4 bit constant is a contiguous sequence of hex digits enclosed in single or 
double quotation marks and followed immediately by B4. Each hex digit represents 
four bits. BX is a synonym for B4. The syntax for a bit constant is: 





2 oo ee 
hex-digit “Ley 
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Graphic data 


Some examples of B4 constants are: 


CA'B4 is the same as "1100_1010"B 
80'B4 is the same as '1000_0000'B 
"1'B4 is the same as "Q0001'B 
(2)'F'B4 is the same as os Fe Wy Bi 
(2)'F'B4 is the same as “FF’ BX 

'B4 is the same as a) 


Graphic data 
GRAPHIC data can contain any DBCS character. Each DBCS character occupies 
2 bytes of storage. 


Graphic constant 

A graphic constant is a contiguous sequence of DBCS characters enclosed in 
single or double quotation marks. Graphic constants take up 2 bytes of storage for 
each DBCS character in the constant. 


The syntax for a graphic constant is: 





The GRAPHIC compiler option must be in effect for graphic constants to be 
accepted. If the GRAPHIC ENVIRONMENT option is not specified for STREAM I/O 
files that include graphic constants, the CONVERSION condition is raised. 


GX (hex) graphic constant 

The GX graphic constant is a contiguous sequence of hex digits, in multiples of 4, 
enclosed in single or double quotation marks and followed immediately by GX. 
Each group of 4 hex digits represents one DBCS character. 


The syntax for a GX constant is: 





pe be ________________. 
hex-digit 


Examples: 
"8lal'gx represents one DBCS character 
""gX is the same as ''g 


Note: The use of GX can limit the portability of a program. 


Mixed character data 

Mixed character data can contain SBCS and DBCS characters. Mixed data is 
represented by the CHARACTER data type, and follows the processing rules for 
CHARACTER data. 


The CHARGRAPHIC option of the OPTIONS attribute and the MPSTR built-in func- 
tion can be used to assist in mixed data handling. For more information on 
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M (Mixed) 


CHARGRAPHIC and MPSTR see “OPTIONS option and attribute” on page 121 
and “MPSTR’” on page 415. 


M (Mixed) character constant 

An M constant is a contiguous sequence of DBCS and/or SBCS characters 
enclosed in quotation marks (single or double), followed immediately by the letter 
M. Quotations marks included in the constant follow the rules listed in “Using quo- 
tation marks” on page 25. The length of an M constant is the number of SBCS 
characters between the enclosing quotation marks counting any doubled quotation 
marks as a single character, plus twice the number of DBCS characters in the 
string. 


A null M constant is written as two quotation marks followed by M. 


The syntax for the M constant is: 


—  —— ——— ee eee 
character 
kk 


Examples of mixed character constants are: 





Constant Length 

‘IBM kkkk'M 8 bytes on PS/2*, 10 on S/370 
'.1.B.M'M 6 bytes on PS/2, 8 on S/370 

' 'M 0) 


The GRAPHIC compiler option must be in effect for mixed constants to be 
accepted. If the GRAPHIC ENVIRONMENT option is not specified for STREAM I/O 
files having mixed constants, the CONVERSION condition is raised. 


Note: Because of the use of shift-codes on some computers, the use of mixed 
data and M constants can limit program portability. 


Numeric character data 

A numeric character data item is the value of a variable that has been declared 
with the PICTURE attribute with a numeric picture specification. The data item is 
the character representation of a decimal fixed-point or floating-point value. 


Numeric picture specification describes a character string that can be assigned only 
data that can be converted to an arithmetic value. 


For example: 
declare Price picture '999V99'; 


specifies that any value assigned to Price is maintained as a character string of five 
decimal digits, with an assumed decimal point preceding the rightmost two digits. 
Data assigned to Price is aligned on the assumed point in the same way that point 
alignment is maintained for fixed-point decimal data. 


Numeric character data has arithmetic attributes, but it is not stored in coded arith- 


metic form. Numeric character data is stored as a character string. Before it can 
be used in arithmetic computations, it must be converted either to decimal fixed- 
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Numeric character data 


point or to decimal floating-point format. Such conversions are done automatically, 
but they require extra processing time. 


Although numeric character data is in character form, like character strings, and 
although it is aligned on the decimal point like coded arithmetic data, it is processed 
differently from the way either coded arithmetic items or character strings are proc- 
essed. Editing characters can be specified for insertion into an numeric character 
data item, and such characters are actually stored within the data item. Conse- 
quently, when the item is printed or treated as a character string, the editing char- 
acters are included in the assignment. However, if a numeric character item is 
assigned to another numeric character or arithmetic variable, the editing characters 
are not included in the assignment—only the actual digits, signs, and the location of 
the assumed decimal point are assigned. For example: 
declare Price picture '$99V.99', 

Cost character (6), 

value fixed decimal (6,2); 
Price = 12.28% 
Cost = '$12.28'; 


In the picture specification for PRICE, the currency symbol ($) and the decimal 
point (.) are editing characters. They are stored as characters in the data item. 
However, they are not a part of its arithmetic value. After both assignment state- 
ments are executed, the actual internal character representation of Price and Cost 
can be considered identical. If they were printed, they would print exactly the 
same; but they do not always function in the same way. For example: 


Value = Price; 


Cost = Price; 
Value = Cost; 
Price = Cost; 


After the first two assignment statements are executed, the value of Value is 
0012.28 and the value of Cost is '$12.28'. In the assignment of Price to Value, the 
currency symbol and the decimal point are editing characters, and they are not part 
of the assignment. Tne numeric vaiue of Price is converted to internal coded arith- 
metic form. In the assignment of Price to Cost, however, the assignment is to a 
character string, and the editing characters of a numeric picture specification 
always participate in such an assignment. No conversion is necessary because 
Price is stored in character form. 


The third and fourth assignment statements would raise the CONVERSION condi- 
tion. The value of Cost cannot be assigned to Value because the currency symbol 
in the string makes it invalid as an arithmetic constant. The value of Cost cannot 
be assigned to Price for the same reason. Only values that are of arithmetic type, 
or that can be converted to arithmetic type, can be assigned to a variable declared 
with a numeric picture specification. 


Although the decimal point can be an editing character or an actual character in a 
character string, it will not raise the CONVERSION condition in converting to arith- 
metic form, since its appearance is valid in an arithmetic constant. The same is 
true for a valid plus or minus sign, because converting to arithmetic form provides 
for a sign preceding an arithmetic constant. 


Other editing characters, including zero suppression characters, drifting characters, 
and insertion characters, can be used in numeric picture specifications. For a com- 
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plete discussion of picture characters, see Chapter 14, “Picture specification 
characters.” 


Named constants 


A named constant is a scalar identifier declared with the VALUE attribute along with 
other data attributes. All references to the name are logically treated as a refer- 
ence to the appropriate constant but with the complete set of attributes, whether 
explicitly declared or defaulted. 


Note: The effect of the use of a named constant may not be exactly the same as 
the use of an unnamed constant. The attributes for a named constant are 
taken from the declaration which includes explicit and default attributes. 
The attributes for an unnamed constant are deduced from the shape, form, 
and size of the constant. For string data, if the length is not specified, or is 
specified with an asterisk, the length is determined from the length of the 
restricted expression. 


Named constants can be more precise to use in an application program, 
and they can offer more predictable results. For example, if the named 
constant Unit is defined as FIXED BIN VALUE(1), it has the attributes 
FIXED BINARY(15) VALUE(1). If you simply use the digit 1, its attributes 
are FIXED DECIMAL(1,0). See Figure 15 on page 46 for other differences 
that can occur. 


In addition, named constants allow you to set parameters in your application, which 
makes it easier to debug and maintain. 


Named constants can be used wherever a constant is required. They can also be 
used in restricted expressions that appear later in the program permitting evaluation 
of a dependent constant. 


Named constants can be declared for arithmetic data, string data, and for pointers 
and offsets. For arithmetic and string data and their attributes, see “String data and 
attributes” on page 37 and “Coded arithmetic data and attributes” on page 30 
respectively. A named constant must be declared before it is used. 


VALUE attribute 
The syntax for the VALUE attribute is: 


p>>—VALUE( restricted-express i on)-——_———_——____—__—__—__—__—__ >» 


restricted expression 
the expression must evaluate to a scalar value. For information on 
restricted expressions see “Restricted expressions” on page 68. 


Examples of named constants 


Figure 15 shows named constants and the differences in attributes and precisions 
that can occur between named and unnamed constants. 
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Program control data 


a4 value(148) fixed bin, 

c4 value(261) fixed bin, 

whole value(800Q) fixed bin; 

notes (4) static, 

init(a4, (whole/4), /* 148, 200 */ 
c4, (whole*2)); /* 261, 1600 */ 


/* note that “Head” gets length equal to length of VALUE */ 


Dcl Head char VALUE('Feel the Power of PL/I'); /* char(22) */ 
Del Headsize fixed bin value(length(Head)); [* 22 */ 
Dcl 1 Headl static, 
2 * char(Headsize) initial (Head), /* char(22) */ 
.2 * char(20) init(''), 
2 * char(5) init('Page '), 
2 Page_number pic 'zz9', 
2 * char(0); 
Dcl TwoHeads char(2*Headsize); J Char (aa )- Fy 
Del Page@ Picture 'zz9' value(Q); 
Dcl MyNullPtr ptr value(ptrvalue('fttf_fftf'xn) ); 


/* Differences in attributes/results of 
named and unnamed constants */ 


Del pi float bin value (3.1416); /* is FLOAT BIN(21) but ... */ 
3.1416 /* is FIXED DECIMAL(5,4) 


Dcl Unit fixed bin value(l); /* is FIXED BIN(15) but .. 
/* 15 FIXED DECIMAL(1,0) 
/* is FIXED DECIMAL(2,1) 
/* is FIXED BIN(1) 

0000_0000_0000_001B /* is FIXED BIN(15) 








Dcl title char(20) value('SCIDS'); /* is CHAR(20) but ... 
Del title2 char value('SCIDS');/* is CHAR(5) 
“SULDS: /* is CHAR(5) 





Figure 15. Named constants 


Program control data types and attributes 


This section describes program control data and associated attributes. Use 
program control data to indicate values that control the execution of your program. 


Label data and LABEL attribute 


A label data item is a label constant or the value of a label variable. 


The LABEL attribute specifies that the declared name is a label variable and can 
have label constants as values. 


>>—LABEL AAA i > 


A label constant is a name written as the label prefix of a statement (other than 
PROCEDURE, PACKAGE, or FORMAT) so that during execution, program control 
can be transferred to that statement through a reference to it. (“Statements” on 
page 17 discusses the syntax of the label prefix.) 


46 PL/I Package/2 Language Reference 


Format data and FORMAT attribute 


In the example: 
Abcde: Miles = Speed*Hours; 


Abcde is a label constant. The labelled statement can be executed either by normal 
sequential execution of instructions or by using the GO TO statement to transfer 
control to it from some other point in the program. 


A label variable can have another label variable or a label constant assigned to it. 
When such an assignment is made, the environment of the source label is 
assigned to the target. 


A label variable used in a GO TO statement must have as its value a label constant 
that is used in a block that is active at the time the GO TO is executed. If the 
variable has an invalid value, the detection of such an error is not guaranteed. For 
example: 

declare LbI_x label; 

Lbl_a: statement; 


Lbl_b: statement: 
Lbi_x = Lbl_a; 
go to Lb1_x; 


Lbl_a and Lb!|_b are label constants, and Lb1_x is a label variable. By assigning 
Lbl_a to Lb1_x, the statement GO TO Lb1_x transfers control to the Lb|1_a statement. 
Elsewhere, the program can contain a statement assigning Lb1_b to Lb]_x. Then, 
any reference to Lb1_x would be the same as a reference to Lbl_b. This value of 
Lb1_x Is retained until another value is assigned to it. 


In the following example, transfer is made to a particular element of the array Z 
based on the value of I. 


go to Z(1); 


Z(1): if X = Y then return; 


12): A= he BEC * D: 


Z(3): A=A+t 10; 


If Z(2) is omitted, GO TO Z(1) when I=2 raises the ERROR condition. GO TO Z(1) 
when | < LBOUND(Z) or I > HBOUND(Z) Causes unpredictable results if the 
SUBSCRIPTRANGE condition is disabled. 


Format data and FORMAT attribute 


A format data item is a format constant or a format variable. A format constant is a 
name written as the label prefix of a FORMAT statement. 


The FORMAT attribute specifies that the name being declared is a format variable. 
Its syntax is: 


pm» —F RMA ___$_________§_—_—________>« 
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VARIABLE 


A name declared with the FORMAT attribute can have another format variable or a 
format constant assigned to it. When such an assignment is made, the environ- 
ment of the source label is assigned to the target. 


In the example: 


Prntexe: format 

( column(20),A(15), column(40),A(15), column(60),A(15) ); 
Prntstf: format 

( column(20),A(10), column(35),A(10), column(50),A(10) ); 


Prntexe and Prntstf are the format constants. 


Consider the example: 


dcl Print format; 

Jif put edit (X,Y,Z) (R(Prntexe) ); 

fe] put edit (X,Y,Z) (R(Prntstf) ); 
Print = Prntexe; 

Bf put edit (X,Y,Z) (R(Print) ); 
Print, = /PRHUS tf: 

(yo put edit (X,Y,Z) (R(Print) ); 


in which [1[ and [BJ have the same effect, as do |2J and f4f. 


VARIABLE attribute 


The VARIABLE aitribute establishes the name as a variable and is needed only for 
scalar ENTRY and FILE variables. 


Refer to “Entry variables” on page 113 or “File variable” on page 232 for informa- 
tion about these items. 


The syntax for the VARIABLE attribute is: 


>> —V AR TABL¢- 


The VARIABLE attribute is implied if the name is a member of a structure or union, 
or if any of the following attributes is specified: 


Storage class attribute 
DIMENSION 
PARAMETER 
Alignment attribute 
INITIAL 


In the following declaration, Account1 and Account2 are file variables and Filel and 
File2 are file constants. 
declare Accountl file variable, 

Account2 file automatic, 

Filel file, 

File2 file; 


Filel and File2 can subsequently be assigned to Account] or to Account2. 
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This chapter discusses the various types of expressions and references. 


An expression is a representation of a value. An expression can be the following: 
* A single constant, variable or function reference | 


* Any combination of constants, variables or function references, including opera- 
tors and parentheses used in the combination. 


An expression that contains operators is an operational expression. The constants 
and variables of an operational expression are called operands. See “Operational 
expressions” on page 53 for more information on operational expressions. 


The syntax for expressions and references is: 


>» unary-expression ees 
infix-operator“Lunary-expressio 


unary-expression: 


ton elementary-expression ,}_-———_____ 
prefix-operator 


elementary-expression: 
(expression) 
reference 
constant 
reference: 


basic-reference,--————————_____—____» 
locator-qualifier 
> ( )————__—__—_——_—_] 
(+ subscript-list }) Ly argument -list LI 


locator-qualifier: 
| rnFfananra = ‘ 
{Pek Bet CcHuUCo™ 7 a cSs$«.oODWw—wuwowonm | 
basic-reference: 


identi fier —____________| 
qualified-reference 


subscript-list: 


* 


argument-list: 


ce 


qualified-reference: 
[—basic- Cog RN ee ee ee ee ee | 
(+ subscript-list }) 


Notes: 
Operators are shown in Figure 8 on page 15. 


Locator-qualifier is described under “Locator qualification” on page 206. 

identifiers are described under “Identifiers” on page 14. 

Qualified-reference is described under “Structure/union qualification” on page 150. 
Subscripts are described under “Arrays” on page 144. 

Arguments are described in “Passing arguments to procedures” on page 108. 
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Any expression can be classified as an element expression (also called a scalar 
expression) or an array expression. Element variables and array variables can 
appear in the same expression. 


An element expression 
represents an element value. This definition includes an elemen- 
tary name within a structure or a union or a subscripted name that 
specifies a single element of an array. 


An array expression 
represents an array of values. This definition includes a member 
of a structure or union that has the dimension attribute. 


Given the following example: 


dcl A(10,10) bin fixed(31), 
B(10,10) bin fixed(31), 
1 Rate, 
2 Primary dec fixed(4,2), 
2 Secondary dec fixed(4,2), 
1Costt2), 
2 Primary dec fixed(4,2), 
2 Secondary dec fixed(4,2), 
C bin fixed(15), 
D bin fixed(15); 
dcl Pi bin float value(3.1416); 


The following expressions are element expressions: 
Pj 

2/ 

if 

C*D 

A(3,2) + B(4,8) 

Rate.Primary - Cost.Primary(1) 
A(4,4) * C 

Rate.Secondary / 4 

A(4,6) * Cost.Secondary(2) 
sum(A) 

addr( Rate) 


The following expressions are array expressions: 


SD) 
0B 


BY Yr > 
ne a ot 
me Ow 


The syntax of many PL/I statements allows expressions, provided the result of the 
expression conforms with the syntax rules. Unless specifically stated in the text 
following the syntax specification, the unqualified term expression or reference 
refers to a scalar expression. For expressions other than a scalar expression, the 
type of expression is noted. For example, the term array expression indicates that 
a scalar expression is not valid. 
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Evaluation order 


PL/I statements often contain more than one expression or reference. Except as 
described for specific instances (for example, the assignment statement), evaluation 
can be in any order, or (conceptually) at the same time. 


For example: 


del (X,Y,Z) entry returns(float), (F,G,H) float; 
F = X( Y(G,H), Z(G,H) ); 


The functions Y and Z may change the value of the arguments passed to them. 
Hence, the value returned by X may be different depending on which function is 
invoked first. You should not presume that the first parameter is evaluated first. In 
some situations, it is more optimal to evaluate the last first. 


Assuming that the INC function increments the value of the argument passed to it 
and returns the updated value, the example that follows could put out B(1,2) or 
B(2,1) depending on which subscript is evaluated first. You should not presume 
which subscript is evaluated first. 

del -BC2;2);3 

[= 03 

pubs list Be INCCL).. INCL): os 


Targets 
The results of an expression evaluation or of a conversion are assigned to a target. 
Targets can be variables, pseudovariables, or intermediate results. 

Variables 
In the case of an assignment, such as the statement: 
A= B: 
the target is the variable on the left of the assignment symbol (in this case A). 
Assignment to variables can also occur in stream I/O, DO, DISPLAY, and record 
I/O statements. 

Pseudovariables 


A pseudovariable represents a target field. For example: 


declare A character(10), 
B character(30); : 
substr(A,6,5) = substr(B,20,5); 


In this assignment statement, the SUBSTR built-in function extracts a substring of 
length 5 from the string B, beginning with the twentieth character. The SUBSTR 
pseudovariable indicates the location, within string A, that is the target. Thus, the 
last 5 characters of A are replaced by characters 20 through 24 of B. The first 5 
characters of A remain unchanged. 


Pseudovariables can be used only in assignment statements. They are discussed 
in Chapter 17, “Built-in functions, pseudovariables, and subroutines.” 
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Intermediate results 


When an expression is evaluated, the target attributes usually are partly derived 
from the source, partly from the operation being performed, and partly from the 
attributes of a second operand. Some defaults may be used, and some implemen- 
tation restrictions (for example, maximum precision) and conventions exist. An 
intermediate result may undergo conversion if a further operation is to be per- 
formed. After an expression is evaluated, the result may be further converted for 
assignment to a variable or pseudovariable. These conversions follow the same 
rules as the conversion of programmer-defined data. For example: 
declare A character(8), 

B fixed decimal(3,2), 


C fixed binary(10); 
A=B+(C; 


During the evaluation of the expression B + C and during the assignment of that 
result, there are four different results: 


1. The intermediate result to which the converted binary equivalent of B is 
assigned 


2. The intermediate result to which the binary result of the addition is assigned 


3. The intermediate result to which the converted decimal fixed-point equivalent of 
the binary result is assigned 


4. A, the final destination of the result, to which the converted character equivalent 
of the decimal fixed-point representation of the value is assigned. 


The attributes of the first result are determined from the attributes of the source B, 
from the operator, and from the attributes of the other operand. If one operand of 
an arithmetic infix operator is binary, the other is converted to binary before evalu- 
ation. 


The attributes of the second result are determined from the attributes of the source 
(C and the converted representation of B). 


The attributes of the third result are determined in part from the source (the second 
result) and in part from the attributes of the eventual target A. The only attribute 
determined from the eventual target is DECIMAL (a binary arithmetic representation 
must be converted to decimal representation before it can be converted to a char- 
acter value). 


The attributes of A are known from the DECLARE statement. 


Operational expressions 


An operational expression consists of one or more single operations. A single 
operation is either a prefix operation (an operator preceding a single operand) or an 
infix operation (an operator between two operands). The two operands of any infix 
operation normally should be the same data type when the operation is performed. 


The operands of an operation in a PL/I expression are converted, if necessary, to 


the same data type before the operation is performed. Detailed rules for conver- 
sion can be found in Chapter 5, “Data conversion” on page 72. 
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There are few restrictions on the use of different data types in an expression. 
However, these mixtures imply conversions. If conversions take place at run time, 
the program takes longer to run. Also, conversion can result in loss of precision. 
When using expressions that mix data types, you should understand the relevant 
conversion rules. 


There are five classes of operations—pointer, arithmetic, bit, comparison, and con- 
catenation. 


Pointer Operations 
The following pointer support extensions can be used. 


* Add an expression to or subtract an expression from a pointer expression. The 
expression type must be computational. If necessary, the nonpointer operand 
is converted to FIXED BIN(M,0). For example: 


PERI ="P Rit e L6¢ 
PHRZ ="PERL ee Ps 


You can also use the built-in function, POINTERADD, to perform these oper- 
ations. You must use POINTERADD if the result is to be used as a locator 
reference. For example: 


(PTRI + 16) -> BASED_PTR is invalid 


POINTERADD(PTR1,16) -> BASED_PTR is valid 

* Subtract two pointers to obtain the logical difference. The result is a FIXED 
BIN(M,0) value. For example: 
BIN31 = PTR2 - PTR1; 


* Compare pointer expressions using infix operators. For example: 


IF PTR2 > PTR1 THEN 
BINSE = PTR2 =. PTRIs 


* Use pointer expressions in arithmetic contexts using the built-in function, 
BINARYVALUE. For example: 
BIN31 = BIN31 + BINARYVALUE(PTR1); 

° Use computational expressions in pointer contexts using the built-in function, 
POINTERVALUE. For example: 


DCL 1 CVTPTR POINTER BASED( POINTERVALUE( 16) ); 
DCL 1 CVT BASED(CVTPTR), 
LNT teas 


If necessary, the expressions will be converted to FIXED BIN(M,0). 
A PL/I block can use pointer arithmetic to access any element within a structure or 


an array variable. However, the block must be passed the containing structure or 
array variable, or have the referenced aggregate within its name scope. 


Arithmetic operations 


An arithmetic operation is specified by combining operands with one of these oper- 
ators: 


= * / xk 


The plus sign and the minus sign can appear as prefix operators or as infix opera- 
tors. All other arithmetic operators can appear only as infix operators. (Arithmetic 
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operations can also be specified by the ADD, SUBTRACT, DIVIDE, and MULTIPLY 
built-in functions.) 


Prefix operators can precede and be associated with any of the operands of an 
infix operation. For example, in the expression A*-B, the minus sign indicates that 
the value of A is to be multiplied by -1 times the value of B. 


More than one prefix operator can precede and be associated with a single vari- 
able. More than one positive prefix operator has no cumulative effect, but two neg- 
ative prefix operators have the same effect as a single positive prefix operator. 


Data conversion in arithmetic operations 

The two operands of an arithmetic operation may differ in type, base, mode, preci- 
sion, and scale. When they differ, conversion takes place as described below. 
(For coded arithmetic operands, you can also determine conversions using 

Figure 16 on page 57. Each operand is converted to the type, base, and mode of 
the result. It is not necessarily converted to the result's precision and scale.) 


Note: Scaled FIXED BINARY operands are converted to scaled FIXED DECIMAL 
before any operations on them are performed. 


Type: Character operands are converted to FIXED DECIMAL(N,0). Bit operands 
are converted to FIXED BIN(M,0). (Refer to Appendix A, “Limits” on page 465 for 
the maximums.) Numeric character operands are converted to DECIMAL with 
scale and precision determined by the picture-specification. Graphic variables and 
strings are allowed in all computational contexts. If conversion is necessary, the 
rules followed are the same as for character. 


The result of an arithmetic operation is always in coded arithmetic form. Type con- 
version is the only conversion that can take place in an arithmetic prefix operation. 


Base: \f the bases of the two operands differ, the decimal operand is converted to 
binary. 

Mode: lf the modes of the two operands differ, the real operand is converted to 
complex mode by acquiring an imaginary part of zero with the same base, scale, 
and precision as the real part. The exception to this is in the case of 
exponentiation when the second operand (the exponent of the operation) is fixed- 
point real with a scaling factor of zero. In such a case, conversion is not neces- 


sary. 


Precision: \f only precisions and/or scaling factors vary, type conversion is not 
necessary. 


Scale: \f the scales of the two operands differ, the fixed-point operand is con- 
verted to floating-point scale. The exception to this is in the case of exponentiation 
when the first operand is of floating-point scale and the second operand (the expo- 
nent of the operation) is fixed-point with a scaling factor of zero, that is, an integer 
or a variable that has been declared with precision (p,0). In such a case, conver- 
sion is not necessary, but the result is floating-point. 


If both operands of an exponentiation operation are fixed-point, conversions can 
occur in one of the following ways: 


* Both operands are converted to floating-point if the exponent has a precision 
other than (p,0). 
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° The first operand is converted to floating-point unless the exponent is an 
unsigned integer. 


* The first operand is converted to floating-point if precisions indicate that the 
result of the fixed-point exponentiation would exceed the maximum number of 
digits allowed. 


Results of arithmetic operations 

After any necessary conversion of the operands in an expression has been carried 
out, the arithmetic operation is performed and a result is obtained. This result can 
be the value of the expression, or it can be an intermediate result upon which 
further operations are to be performed, or a condition can be raised. 


Figure 16 shows the attributes and precisions that result from various arithmetic 
operations, and Figure 18 shows the attributes of the result for the special cases of 
exponentiation noted in the right-hand column of Figure. 16. 


Conversion of operands: \n Figure 17 on page 58, if both operands are FIXED 
and either has a nonzero scale factor, any FIXED BIN operands are converted to 
FIXED DECIMAL using the following rules: 


Given And And The results are 
q<0O p>=q ceil( (p-q/3.32 ) +9) < N r=N 
s = ceil( (p-q)/3.32 )+q-N 
ceil( (p-q)/3.32 )+9)<N r= ceil( (p-q)/3.32 )+q 
s=q 
r=min(N,q ) 
SST 
q<0 ceil( (p-q)/3.32 ) > N r=N 
s =N - ceil( (p-q)/3.32) 
ceil( (p-q)/3.32 ) < N r = ceil( (p-q)/3.32 ) 
s=0 


For example, FIXED BIN(15,2) is converted to FIXED DEC(6,2). FIXED BIN(15,—2) 


is converted to FIXED DECiiMAL(6,0). 
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Figure 16. Results of arithmetic operations for one or more FLOAT operands 


1st 
Operand 
(p1,q1) 

FLOAT 
DECIMAL 
(P) 
FLOAT 
DECIMAL 
(P4) 
FIXED 
DECIMAL 
(P1,44) 
FLOAT 
BINARY 
(P4) 
FLOAT 
BINARY 
(p;) 
FIXED 
BINARY 
(P7,44) 
FIXED 
DECIMAL 
(P4,94) 
FLOAT 
DECIMAL 
(P41) 
FLOAT 
DECIMAL 
(p4) 
FIXED 
BINARY 
FLOAT 
BINARY 
(P41) 
FLOAT 
BINARY 
(P1) 
Notes: 











Attributes of 
the Result for 
































Addition, Multipli- Attributes 
2nd Subtraction, Addition or cation of the 
Operand Multiplication, Subtraction Preci- Division Result for 
(p2,q2) or Division Precision sion Precision Exponentiation 





FLOAT 
DECIMAL 
(Po) 
FLOAT 

DECIMAL 
FLOAT 

DECIMAL 
(Po) 








FLOAT DECIMAL (p) 
(unless special case 
C applies) 

p = MAX(P1,po) 











FLOAT 
DECIMAL (p) 





p = MAX(py,P5) 


FLOAT BINARY (p) 
(unless special case 
C applies) 

p = MAX(Py,Pp) 






FIXED 
BINARY 


FLOAT 
BINARY 
(P2,d2) 
FLOAT 
BINARY 
(Po) 
FLOAT 
BINARY 
(P4,d2) 








FLOAT 
BINARY (p) 















FLOAT BINARY (p) 
(unless special case A 
or C applies) 


MAX(CEIL(p4—3.32),po) 























FLOAT 


BINARY (p) p = MAX(CEIL(p4*3.32),po) 






FLOAT 
DECIMAL 


(Po) 












FLOAT BINARY (p) 





















FIXED FLOAT (unless special case B 
DECIMAL BI Yy p = MAX(p,,CEIL(p5*3.32)) or C applies) 
(Po,d9) MABE?) “a 


SAE MAX(p,,CEIL(p—3.32)) 


DECIMAL 
(Po) 







1. Special cases of exponentiation are described in Figure 18 on page 59. 


2. For a table of CEIL(N*3.32) values, see “Conversion of operands” on page 56. 
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Figure 17. Results of arithmetic operations between two FIXED operands 


Attributes of 
the Result for 


Addition, 
ist 2nd Subtraction, 

Operand Operand Multiplication, 

(p1,q1) (p2,q2) or Division 
FIXED FIXED 
DECIMAL | DECIMAL SECiNAL (p,q) 
(P1,41) (P2,d2) | 
FIXED FIXED 
BINARY pagal BINARY (p,0) 
(P4 ,0) (Po,0) | 
FIXED FIXED 
DECIMAL | BINARY cee (p,0) 
(Py ,0) (Po,0) ji 
FIXED FIXED 
DECIMAL | BINARY Cini (p,q) 
(P1,44) (P2,0) | 
FIXED FIXED 
BINARY DECIMAL BINARY (p,0) 
(P4 ,0) (P2,0) ! 
FIXED FIXED 
BINARY Bec aer Soin (p,q) 
(p;,0) (P2,42) | 


M is the maximum precision for FIXED BIN. 
N is the maximum precision for FIXED DEC. 
r= 1+ CEIL(p,—3.32) 

s = CEIL(ABS(q,-3.32)) * SIGN(q,) 


Notes: 


Multipli- 
cation 
Preci- 


Addition or 
Subtraction 
Precision 


p=1 
+MAX(p4—q1,Po~Go) 
+q 

q = MAX(q1,49) 


Division 
Precision 


p=1 
+MAX(p4—q4,P2-do) 


+MAX(r,Po) 


+MAX(p4—-qy,Vv) +q 
q=q 


p = 1+MAX(p,,t) 
q=0 


p=1 
+MAX(po-Go,w) +q 
q = 
t= 1 + CEIL(p5—3.32) 
u = CEIL(ABS(qp*3.32)) * SIGN(qs) 
v = CEIL(p2/3.32) 
w = CEIL(p,/3.32) 





The scaling factor must be in the range —128 through +127. 


1. Special cases of exponentiation are described in Figure 18 on page 59. 
2. For a table of CEIL(N*3.32) values, see Figure 23 on page 76. 
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Attributes 

of the 

Result for 
Exponentiation 


| FLOAT DECIMAL (p) 


(unless special case 
A applies) 
p = MAX(p;,P2) 


FLOAT BINARY (p) 
(unless special case 
B applies) 

p = MAX(p,,Po) 


FLOAT BINARY (p) 
(unless special case A 
or C applies) 

p = MAX(CEIL 
(p4-3.32 ),Po) 


FLOAT BINARY (p) 
(unless special case A 
or C applies) 

p = MAX(CEIL 
(p1-3.32 ),Po) 


Results of arithmetic operations 


Figure 18. Special cases for exponentiation 


Case First Operand Second Operand Attributes of Result 
A FIXED DECIMAL Integer with FIXED DECIMAL (p,q) 
(p1,q1) value n (provided p <= N) 
where p = (p1 + 1)*n-1 
and q =q1*n 
B FIXED BINARY Integer with FIXED BINARY (p,q) 
(p1,q1) value n (provided p <= M) 
where p = (p1 + 1)*n-1 
and q = pi*n 
Cc FLOAT (p1) FIXED (p2,0) FLOAT (p1) 


with base of first operand 


Special cases of x**y in real/complex modes: 


Real mode: Complex mode: 

If x=0 and y>0, result is 0. If x=0, and real part of y>O and imaginary part of 
y=0, result is 0. 

if x=0 and y<=0, ERROR condition is raised. If x=0 and real part of y<=0 or 


imaginary part of y —=0, ERROR condition is raised. 


lf x<0 and y not FIXED (p,0), ERROR condition is raised. If x-=0 and real and imagi- 
nary parts of y=0, result is 1. 


Consider the expression: 
A*B+C 
The operation A * B is performed first, to give an intermediate result. Then the 


value of the expression is obtained by performing the operation (intermediate result) 
aoe 


PL/I gives the intermediate result attributes the same way it gives attributes to any 
variable. The attributes of the result are derived from the attributes of the two oper- 
ands (or the single operand in the case of a prefix operation) and the operator 
involved. The way the attributes of the result are derived is further explained under 
“Targets” on page 52. 


The ADD, SUBTRACT, MULTIPLY, and DIVIDE built-in functions allow you to over- 
ride the implementation precision rules for addition, subtraction, multiplication, and 
division operations. 


FIXED division: FIXED division can result in overflows or truncation. For 
example, the result of evaluating the expression: 


25+1/3 


is undefined and the FIXEDOVERFLOW condition is raised because FIXED division 
results in a value of maximum implementation defined precision. 


For the following expression, however: 
25+01/3 
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The result is 25.3333333333333 (when the maximum precision is 15) because con- 
stants have the precision with which they are written. The results of the two evalu- 
ations are reached as shown in Figure 19: 


Figure 19. Comparison of FIXED division and constant expressions 


Item Precision Result 
1 (1,0) 1 
3 (1,0) 3 
1/3 (15,14) 0.33333333333333 
25 (2,0) 25 
254+1/3 (15,14) undefined 


(truncation on left; 
FIXEDOVERFLOW is raised 
when the maximum 
precision is 15) 


01 (2,0) 01 

3 (1,0) 3 
01/3 (15,13) 00.3333333333333 

25 (2,0) 25 
25+01/3 (15,13) 25.3333333333333 


The PRECISION built-in function can also be used. For example: 
25t+prec(1/3,15,13) 


Note: Named constants are recommended for situations that require exact pre- 
cisions. 


Bit operations 
A bit operation is specified by combining operands with one of the following logical 
operators: 


= & | 


The not/exclusive-or symbol (—), can be used as a prefix or infix operator. The and 
(&) symbol and the or (I) symbol, can be used as infix operators only. (The opera- 
tors have the same function as in Boolean algebra.) 


Operands of a bit operation are converted, if necessary, to bit strings before the 
operation is performed. If the operands of an infix operation do not have the same 
length, the shorter is padded on the right with '0'B. 


The result of a bit operation is a bit string equal in length to the length of the oper- 
ands. 


Bit operations are performed on a bit-by-bit basis. Figure 20 illustrates the result 
for each bit position for each of the operators. Figure 21 on page 61 shows some 
examples of bit operations. 


/ 
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| Figure 20. Bit operations | 





Figure 21. Bit operation examples 


For these operands and values This operation Yields this result 
A= '010111'B aA ‘101000'B 

B= '111111'B ; ; 

C= '110'B = C 001'B 

D= 5 C&B '110000'B 


A\B "111111'B 
A-=B '101000''B 
AAC '100111'B 
GlG '111111'B 


A | (=C) '011111'B 
—a((-C)1(-B)) '110111'B 
SUBSTR(A, 1,1) 1(D=5) ‘1'B 


BOOL built-in function 

In addition to the not, exclusive-or, and, and or operations using the operators —, &, 
and |, Boolean operations can be performed using the BOOL built-in function dis- 
cussed in “BOOL” on page 387. 


Comparison operations 


A comparison operation is specified by combining operands with one of the fol- 
lowing infix operators: 


Vv 


—> 


The result of a comparison operation is always a bit string of length 1. The value is 
'1'B if the relationship is true, or '0'B if the relationship is false. 


Note: Scaled FIXED BINARY operands are converted to scaled FIXED DECIMAL 
before any operations on them are performed. Given a variable with the attributes 
FIXED BIN(p,q) where q is nonzero, the variable will be converted to FIXED 
DEC(r,s) where r and s are determined as described in “Conversion of operands” 
on page 56. 


Comparisons are defined as follows: 


Algebraic is the comparison of signed arithmetic values in coded arith- 
metic form. If operands differ in base, scale, precision, or 
mode, they are converted in a manner analogous to arith- 
metic operation conversions. Numeric character data is con- 
verted to coded arithmetic before comparison. Only the 
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operators = and —= are valid for comparison of operands that 
are complex numbers. 


Character is a left-to-right, character-by-character comparison of char- 
acters according to the binary value of the bytes. 

Bit is a left-to-right, bit-by-bit comparison of binary digits. 

Graphic is a left-to-right, symbol-by-symbol comparison of DBCS 


characters. The comparison is based on the binary values of 
the DBCS characters. 


Pointer and offset data 
is a comparison of pointer and offset values containing any 
relational operators. However, the only conversion that can 
take place is offset to pointer. 


Program control data 
is a comparison of the internal coded forms of the operands. 
Only the comparison operators = and —= are allowed; area 
variables cannot be compared. No type conversion can take 
place; all type differences between operands for program 
control data comparisons are in error. 


Comparisons are equal for the following operands: 


Entry In a comparison operation, it is not an error to 
specify an entry variable whose value is an entry 
point of an inactive block. 


Format Format labels on the same FORMAT statement 
compare equal. 


File If the operands represent file values, all of whose 
parts are equal. 


Label Labels on the same statement compare equal. In 
a comparison operation, it is not an error to 
Specily a iabei variabie whose vaiue is a iabei 
constant used in a block that is no longer active. 
The label on a compound statement does not 
compare equal with that on any label contained in 
the body of the compound statement. 


If the operands of a computational data comparison have data types that are appro- 
priate to different types of comparison, the operand of the lower precedence is con- 
verted to conform to the comparison type of the other. The precedence of 
comparison types is (1) algebraic (highest), (2) graphic, (3) character, (4) bit. For 
example, if a bit string is compared with a fixed decimal value, the bit string is con- 
verted to fixed binary for algebraic comparison with the decimal value. The decimal 
value is also converted to fixed binary. 


In the comparison of strings of unequal lengths, the shorter string is padded on the 
right. This padding consists of: 


* Blanks in a character comparison 
° '0'B in a bit comparison 
* A graphic (DBCS) blank in a graphic comparison. 


62 PL/I Package/2 Language Reference 


Concatenation operations 


The following example shows a comparison operation in an IF statement: 


is eee eee 
then action-if-true; 
else action-if-false; 


The evaluation of the expression A = B yields either '1'B, for true, or '0'B, for false. 


In the following assignment statement: 
X=A <=B; 


the value '1'B is assigned to X if A is less than B; otherwise, the value '0'B is 
assigned. 


In the following assignment statement: 
KS ABs 
the first equal symbol is the assignment symbol; the second equal symbol is the 


comparison operator. The value '1'B is assigned to X if A is equal to B; otherwise, 
the value '0'B is assigned. 


An example of comparisons in an arithmetic expression is: 
(X<O)*A + (O<=X & X<=100)*B + (100<X)*C 


The value of the expression is A, B, or C and is determined by the value of xX. 


Concatenation operations 


A concatenation operation is specified by combining operands with the concat- 
enation infix operator: 


Concatenation signifies that the operands are to be joined in such a way that the 
last character, bit, or graphic of the operand to the left immediately precedes the 
first character, bit, or graphic of the operand to the right, with nothing intervening. 


The concatenation operator can cause conversion to a string type because concat- 
enation can be performed only upon strings—either character, bit, or graphic. The 
results differ according to the setting of the DEFAULT compiler option: 


Results under DEFAULT(IBM) 


* If one operand is graphic, the result is graphic. 
° If either operand is bit or binary, the result is bit. 
* Otherwise the result is character. 


For example: 


dc] B bin(4) initial(4), 
CbTbCLy thi tial lb): 
putsskip: MsicB. Cs 


/* Produces 'O1001' not 'bhbb41' */ 
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Results under DEFAULT(ANS) 


® If one operand is graphic, the result is graphic. 
* If both operands are bit, the result is bit. 
* Otherwise the result is character. 


For example: 


del B bin(4) initial(4), 
C bit(1) initial('1l'b); 
put skip list-(B | C); 


/* Produces 'Dib41', not '01001' */ 


The result of a concatenation operation is a string whose length is equal to the sum 
of the lengths of the two operands, and whose type (that is, character, bit, or 
graphic) is the same as that of the two operands. 


If an operand requires conversion for concatenation, the result depends upon the 
length of the string to which the operand is converted. 


For these operands and This operation | Yields this result 
values 
A = '010111'B A| 8B '010111_101'B 
B= '101'B 

A B 
C = 'xy,Z' | A | 010111_010111_101'B 
D = 'aa/BB' C | D 'xy,Zaa/BB' 


Debt ‘aa/BBxy,Z' 
— '101aa/BB' 


In the last example, the bit string '101'B is converted to the character string '101' 
before the concatenation is performed. The result is a character string. 


Combinations of operations 


Different types of operations can be combined within the same operational 
expression. Any combination can be used. 


For example: 


declare result bit(3), 

A fixed decimal(1), 

B fixed binary (3), 

C character(2), D bit(4); 
Result =A+B<C&OD; 


Each operation within the expression is evaluated according to the rules for that 
kind of operation, with necessary data conversions taking place before the opera- 
tion is performed, as follows: 


* The decimal value of A is converted to binary base. 
° The binary addition is performed, adding A and B. 
° The binary result is compared with the converted binary value of C. 


* The bit result of the comparison is extended to the length of the bit variable D, 
and the & operation is performed. 
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* The result of the & operation, a bit string of length 4, is assigned to Result 
without conversion, but with truncation on the right. 


The expression in this example is evaluated operation-by-operation, from left to 
right. The order of evaluation, however, depends upon the priority of the operators 
appearing in the expression. 


Priority of operators 
The priority of the operators in the evaluation of expressions is shown in Figure 22. 


Figure 22. Priority of operations and guide to conversions 


Type of Operation Remarks 


Priority 


Notes: 


1 


ie) 


[é) 


prefix +, — 





Result is in coded arithmetic form 


Arithmetic No conversion is required if operand is in coded arith- 
metic form 


Operand is converted to FIXED DECIMAL if it is a 
CHARACTER string or numeric character (PICTURE) 
representation of a fixed-point decimal number 


Operand is converted to FLOAT DECIMAL if it is a 
numeric character (PICTURE) representation of a 
floating-point decimal number 


Operand is converted to FIXED BINARY if it is a BIT 
string 


All non-BIT data converted to BIT 
Result is in coded arithmetic form 


Result is in coded arithmetic form 


Concatenation Refer to “Results under DEFAULT(ANS)” on page 64 
and “Results under DEFAULT(IBM)” on page 63 





Comparison Result is always either '1'B or '0'B 


Bit string All non-BIT data converted to BIT 
All non-BIT data converted to BIT 
All non-BIT data converted to BIT 


1. The operators are listed in order of priority, group 1 having the highest priority and group 7 the lowest. All operators in the same 
priority group have the same priority. For example, the exponentiation operator ** has the same priority as the prefix + and prefix 
— operators and the not operator —. 


2. For priority group 1, if two or more operators appear in an expression, the crder of priority is right to left within the expression; 
that is, the rightmost exponentiation or prefix operator has the highest priority, the next rightmost the next highest, and so on. 
For all other priority groups, if two or more operators in the same priority group appear in an expression, their order or priority is 
their order left to right within the expression. 


The order of evaluation of the expression 
A+B<C&D 


is the same as if the elements of the expression were parenthesized as 
(((A + B) < C) & D) 


The order of evaluation (and, consequently, the result) of an expression can be 
changed through the use of parentheses. Expressions enclosed in parentheses are 
evaluated first, to a single value, before they are considered in relation to sur- 
rounding operators. 
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Array expressions 


The above expression, for example, might be changed as follows: 
(A +B) < (C & D) 


The value of A converts to fixed-point binary, and the addition is performed, yielding 
a fixed-point binary result (resuit_1). The value of C converts to a bit string (if valid 
for such conversion) and the and operation is performed. At this point, the 
expression is reduced to: 


result_l < result_2 


result_2 is converted to binary, and the algebraic comparison is performed, yielding 
a bit string of length 1 for the entire expression. 


The priority of operators is defined only within operands (or sub-operands). Con- 
sider the following example: 


A+(B<C) & (D | E ** F) 


In this case, PL/I specifies only that the exponentiation will occur before the concat- 
enation. It does not specify the order of the evaluation of (DI|E ** F) in relation to 
the evaluation of the other operand (A + (B < C)). 


Any operational expression (except a prefix expression) must eventually be reduced 
to a single infix operation. The operands and operator of that operation determine 
the attributes of the result of the entire expression. In the following example, the & 
operator is the operator of the final infix operation. 


A+B<C &D 
The result of the evaluation is a bit string of length 4. 


In the next example, because of the use of parentheses, the operator of the final 
infix operation is the comparison operator: 


(A +B) < (C&D) 


The evaluation yields a bit string of length 1. . 


Array expressions 


Array expressions (unlike array references) are allowed only in assignment state- 
ments. If the source is an array expression, then the target must be an array of 
scalars. Arrays of structures can be assigned to like arrays of structures. 


Evaluation of an array expression yields an array result. All operations performed 
on arrays are performed element-by-element, in row-major order. Therefore, all 
arrays referred to in an array expression must have the same number of dimen- 
sions, and each dimension must be of identical bounds. 


Array expressions can include operators (both prefix and infix), element variables, 
and constants. The rules for combining operations and for data conversion of oper- 
ands are the same as for element operations. 
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Prefix operators and arrays 


Prefix operators and arrays 


Infix operators 


The operation of a prefix operator on an array produces an array of identical 
bounds. Each element of this array is the result of the operation performed on 
each element of the original array. For example: 


If A is the array 5 3 9 
i ne ee 
6 3 -4 
then -A is the array -5 -3 9 
oo et ees 
“6 =3 <4 


and arrays 


Infix operations that include an array variable as one operand can have an element 
or another array as the other operand. 


Array-and-element operations 

The result of an expression with an element, an array, and an infix operator is an 
array with bounds identical to the original array. Each element of the resulting 
array is the result of the operation between each corresponding element of the ori- 
ginal array and the single element. For example: 


If A is the array BLO.” 8e 
ie od 8 
then A*3 is the array 15 30. 24 
36 339 


and 9>A is the array of 1 0 1 
bit strings of length1 0 @ 1 


The element of an array-element operation can be an element of the same array. 
Consider the following assignment statement: 


A=A * A(1,2); 


Again, using the above values for A, the newly assigned value of A would be: 


50 100 800 
1200 1100 - 300 


That is, the value of A(1,2) is fetched again. 


Array-and-array operations 

If the two operands of an infix operator are arrays, the arrays must have the same 
number of dimensions, and corresponding dimensions must have identical lower 
bounds and identical upper bounds. The result is an array with bounds identical to 
those of the original arrays; the operation is performed upon the corresponding ele- 
ments of the two original arrays. For example: 


If A is the array 3 


and if B is the array 


MHD COrR LPM® PO 
WwWwo dar + 
ef MSM ho 
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then A+B is the array 3 9 10 


10 ll 3 


and AXB is the array oo ey a2 


24 24 2 


and A>B is the array of 1 @ 9 
bit strings of length 1 Os tah 
] 


0 1 


Restricted expressions 


Where PL/I requires a (possibly signed) constant, a restricted expression can be 
used. A restricted expression is an expression whose value is calculated at 
compile time and used as a constant. For example, you can use expressions to 
define constants required for: 


* Extents in static, parameter, and based declarations 
* Extents in entry descriptions 
* Values and iteration factors to be used in static initialization. 


A restricted expression is identical to a normal expression but requires that each 
operand be: 


* Aconstant or a named constant. A named constant must be declared before it 
is used. 


° A built-in function applied to a restricted expression(s), where the built-in func- 
tion is from the following categories: 


String-handling 


Arithmetic (MAX and MIN must have only two arguments. RANDOM is not 
allowed.) 


Mathematical 

Floating-point inquiry 

Floating-point manipulation 

Integer manipulation 

Precision-handling 

Array-handling functions DIMENSION, LBOUND, and HBOUND 


Storage-control functions BINARYVALUE, LENGTH, NULL, 
OFFSETVALUE, POINTERVALUE, SIZE, STORAGE, and SYSNULL. 
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Examples 


dc] Max_names fixed bin value (1000), 
Name_size fixed bin value (30), 
Addr_size fixed bin value (20), 
Addr_lines fixed bin value (4); 
dcl 1 Name_addr(Max_names), 
2 Name char(Name_size), 
2 * union, 
3 address char(Addr_lines*Addr_size), /* address st 
3 addr(Addr_lines) char(Addr_size), 
2 * char(0); 
dcl One_Name_addr char(size(Name_addr(1))); /* 1 name/addr*/ 
dcl Two_Name_addr char(length(One_Name_addr ) 
*2); /* 2 name/addrs */ 
dc] Name_or_addr char(max(Name_size,Addr_size)) based; 


dcl Ar(10) pointer; 


dcl Ex entry( dim(1bound(Ar):hbound(Ar)) pointer); 
dcl Identical_to_Ar( lbound(Ar):hbound(Ar) ) pointer; 


If you change the value of any of the named constants in the example, all of the 
dependent declarations are automatically re-evaluated. 


Chapter 4. Expressions and references 


69 


70 PL/I Package/2 Language Reference 





© Copyright IBM Corp. 1992 


Chapier 5. Data conversion 


Chapter 5. Dataconversion ....................0000 0004 72 
Built-in functions for computational data conversion ................ 73 
Converting string lengths ............. 02.2000 eee eee eee 74 
Converting arithmetic precision ...........0 20.0... 0000. eee eee 75 
GOMVEMING MODE? i408 cscey ©f 4 ore. Bog a ats Cee cn a Eh aw hehe Seed 75 
Converting other data attributes .....................0., py ae ea ED 
Source-to-target rules «2. eee 77 
EX@MDIOS. | i6 3 A508 8st, SS ete ng leo) 9, Yh a B, @ hie Ds dled Were, She 84 
_ DECIMAL FIXED to BINARY FIXED with fractions ............... 84 
Arithmetic-to-bit-string conversion ............ 0.00000 05 02s 84 
Arithmetic-value-to-character-string conversion ................. 85 

A CONVOISION' GIO! One eek eee en ole Ved 2 bee ere es 85 


71 


Data conversion 





Chapter 5. Data conversion 


72 


This chapter discusses data conversions for computational data. PL/I converts data 
when a data item with a set of attributes is assigned to another data item with a 
different set of attributes. In this chapter, source refers to the data item to be con- 
verted, and target refers to the attributes to which the source is converted. Topics 
discussed for these data conversions include: 


Built-in functions 
String lengths 
Arithmetic precision 
Mode 
Source-to-target rules. 


Examples of data conversion are included at the end of the chapter. 
Data conversion for locator data is discussed in “Locator conversion” on page 205. 


Conversion of the value of a computational data item can change its internal repre- 
sentation, precision or mode (for arithmetic values), or length (for string values). 


The tables that follow summarize the circumstances that can cause conversion to 
other attributes. 


Case — Target Attributes 

Assignment Attributes of variable on left of assignment 
symbol 

Operand in an expression Determined by rules for evaluation of 
expressions 

Stream input (GET statement) Attributes of receiving field 

Stream output (PUT statement) As determined by format list if stream is edit- 
directed, otherwise character-string 

Argument to PROCEDURE Attributes of corresponding parameter 

Argument to built-in function or Depends on the function or pseudovariable 

pseudovariable 

INITIAL attribute Other attributes of variable being initialized 

RETURN statement expression Attributes specified in PROCEDURE statement 

DO statement, BY, TO, or REPEAT Attributes of control variable 

option 


The following can cause conversion to character values: 


Statement Option 

DISPLAY 

Record I/O KEYFROM 
KEY 

OPEN TITLE 
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Built-in functions for computational data conversion 


The following can cause conversion to a BINARY value: 


Statement Option/Attribute/Reference 

DECLARE, ALLOCATE, DEFAULT length, size, dimension, bound, repetition factor 
DELAY milliseconds 

FORMAT (and format items in GET and iteration factor 

PUT) w, d, Ss, p 

OPEN LINESIZE, PAGESIZE 

/O SKIP, LINE, IGNORE 

Most statements subscript 


All attributes for source and target data items (except string length) must be speci- 
fied at compile time. Conversion can raise one of the following conditions: CON- 
VERSION, OVERFLOW, SIZE, or STRINGSIZE. (Refer to Chapter 16, 
“Conditions.”) 


Constants can be converted at compile time as well as at run time. In all cases the 
conversions are as described here. 


More than one conversion might be required for a particular operation. The imple- 
mentation does not necessarily go through more than one. To understand the con- 
version rules, it is convenient to consider them as being separate. For example: 
del A fixed dec(3,2) init(1.23); 


dcl B fixed bin(15,5); 
B= A; 


In this example, the decimal representation of 1.23 is first converted to binary 
(11,7), as 1.0011101B. Then precision conversion is performed, resulting in a 
binary (15,5) value of 1.00111B. 


Additional examples of conversion are provided at the end of this chapter. 


Built-in functions for computational data conversion 


Conversions can take place during expression evaluation, I/O GET and PUT oper- 
ations, and assignment operations, and between arguments and parameters. Con- 
versions can also be initiated with the following built-in functions: 


BINARY FIXED REAL 

BIT FLOAT SIGNED 
CHAR GRAPHIC UNSIGNED 
COMPLEX IMAG 

DECIMAL PRECISION 


Each is discussed in Chapter 17, “Built-in functions, pseudovariables, and 
subroutines.” 


Each function returns a value with the attribute specified by the function name, per- 
forming any required conversions. 


With the exception of the conversions performed by the COMPLEX, GRAPHIC, and 
IMAG built-in functions, assignment to a PL/I variable having the required attribuies 
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Converting string lengths 


can achieve the conversions performed by these built-in functions. However, you 
might find it easier to use a built-in function than to create a variable solely to carry 
out a conversion. 


Converting string lengths 


The source string is assigned to the target string from left to right. If the source 
string is longer than the target, excess characters, bits, or graphics on the right are 
ignored, and the STRINGSIZE condition is raised. For fixed-length targets, if the 
target is longer than the source, the target is padded on the right. If STRINGSIZE 
is disabled, and the length of the source and/or the target is determined at run time, 
and the target is too short to contain the source, unpredictable results might occur. 


Note: If you use SUBSTR with variables as the parameters, and the variables 
specify a string not contained in the target, unpredictable results can occur. 


Character strings are padded with blanks, bit strings with '0'B, and graphic strings 
with DBCS blank. For example: 


declare Subject char(10); 
Subject = 'Transformations'; 


Transformations has 15 characters. Therefore, when PL/I assigns the string to 
Subject, it truncates 5 characters from the right end of the string. This is equivalent 
to executing: 


Subject = 'Transforma'; 


The first two of the following statements assign equivalent values to Subject and 
the last two assign equivalent values to Code: 


Subject = 'Physics'; 
Subject = ‘Physics '; 
declare Code bit(10); 
Code = '110011'B; 

Code = '1100110000'B; 


The following statements do not assign equivalent values to Subject: 


Subject = '110011'B; 
Subject = '1100110000'B; 


When the first statement is executed, the bit constant on the right is first converted 
to a character string and is then extended on the right with blank characters rather 
than zero characters. This statement is equivalent to: 


Subject = '110011bbbb'; 


The second of the two statements requires only a conversion from bit to character 
type and is equivalent to: 


Subject = '1100110000' ; 


A string value is not extended with blank characters or zero bits when it is assigned 
to a string variable that has the VARYING attribute. Instead, the length of the 
target string variable is set to the length of the assigned string. However, trun- 
cation will occur if the length of the assigned string exceeds the maximum length 
declared for the varying-length string variable. 
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Converting arithmetic precision 


When an arithmetic value has the same data attributes, except for precision, as the 
target, precision conversion is required. 


For fixed-point data items, decimal or binary point alignment is maintained during 
precision conversion. Therefore, padding or truncation can occur on the left or 
right. If nonzero bits or digits on the left are lost, the SIZE condition is raised. 


For floating-point data items, truncation on the right, or padding on the right with 
zeros, Can occur. 


Converting mode 


If a complex value is converted to a real value, the imaginary part is ignored. Ifa 
real value is converted to a complex value, the imaginary part is zero. 


Converting other data attributes 


Source-to-target rules are given, following this section, for converting data items 
with the following data attributes: 


* Coded arithmetic: 

FIXED BINARY 

FIXED DECIMAL 

FLOAT BINARY 

FLOAT DECIMAL 
Arithmetic character PICTURE 
CHARACTER 
BIT 
GRAPHIC. 


Changes in value can occur in converting between decimal representations and 
binary representation. In converting between binary and decimal, the factor 3.32 is 
used as follows: 


* n decimal digits convert to CEIL (n*3.32) binary digits. 
* n binary digits convert to CEIL (n/3.32) decimal digits. 


A table of CEIL values is provided in Figure 23 to calculate these conversions. 
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Figure 23. CEIL (n*3.32) and CEIL (n/3.32) values 


CEIL CEIL 

n (n*3.32) n (n/3.32) 
1 4 1-3 1 
2 7 4-6 2 
3 10 7-9 3 
4 14 10-13 4 
5 17 14-16 5 
6 20 17-19 6 
7 24 20-23 7 
8 27 24-26 8 
9 30 27-29 9 
10 34 30-33 10 
11 37 34-36 11 
12 40 37-39 12 
13 44 40-43 13 
14 47 44-46 14 
15 50 47-49 15 
16 53(1) 50-53 16 
17 57 54-56 17 
18 60 57-59 18 
19 64 60-63 19 
20 67 64-66 20 
21 70 67-69 21 
22 74 70-73 22 
23 77 74-76 23 
24 80 77-79 24 
25 83 80-83 25 
26 87 84-86 26 
27 90 87-89 27 
28 93 90-92 28 
29 97 93-96 29 
30 100 97-99 30 
31 103 100-102 31 
32 107. 103-106 32 
33 110. 107-109 33 

110-112 34 

113-116 35 


Note 1: While ceil(16*3.32) = 54, the value 53 is 
used. If it were not, a float dec(16), when converted 
to binary, would have to be converted from long 
floating-point to extended floating-point (because 
float bin(54) is represented as extended floating- 
point). 


For fixed-point integer values, conversion does not change the value. For fixed- 
point fractional values, the factor 3.32 provides only enough digits or bits so that 
the converted value differs from the original value by less than 1 digit or bit in the 
rightmost place. 


For example, the decimal constant .1, with attributes FIXED DECIMAL (1,1), con- 
verts to the binary value .0001B, converting 1/10 to 1/16. The decimal constant 
.10, with attributes FIXED DECIMAL (2,2), converts to the binary value .0001100B, 
converting 10/100 to 12/128. 
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Source-io-iarget rules 


Target: Coded Arithmetic 


Source: 


FIXED BINARY, FIXED DECIMAL, 

FLOAT BINARY, and FLOAT DECIMAL 
These are all coded arithmetic data. Rules for conversion between them are 
given under each data type taken as a target. 


Arithmetic character PICTURE 
Data first converts to decimal with scale and precision determined by the corre- 
sponding PICTURE specification. The decimal value then converts to the base, 
scale, mode, and precision of the target. See the specific target types of coded 
arithmetic data using FIXED DECIMAL or FLOAT DECIMAL as the source. 


CHARACTER 
The source string must represent a valid arithmetic constant or complex 
expression; otherwise, the CONVERSION condition is raised. The constant can 
be preceded by a sign and can be surrounded by blanks. The constant cannot 
contain blanks between the sign and the constant, or between the end of the 
real part and the sign preceding the imaginary part of a complex expression. 


The constant has base, scale, mode, and precision attributes. It converts to the 
attributes of the target when they are independent of the source attributes, as in 
the case of assignment. See the specific target types of coded arithmetic data 
using the attributes of the constant as the source. 


If an intermediate result is necessary, as in evaluation of an operational 
expression, the attributes of the intermediate result are the same as if a decimal 
fixed-point value of precision had appeared in place of the string. (This allows 
the compiler to generate code to handle all cases, regardless of the attributes of 
the contained constant.) Consequently, any fractional portion of the constant 

~ might be lost. See the specific target types of coded arithmetic data using 
FIXED DECIMAL as the source. 


It's possible that, during the initial conversion of the character data item to an 
intermediate fixed decimal number, the value might exceed the default size of 
the intermediate result. If this occurs, the SIZE condition is raised if it is 
enabled. 


If a character string representing a complex number is assigned to a real target, 
the complex part of the string is not checked for valid arithmetic characters and 
CONVERSION cannot be raised, since only the real part of the string is 
assigned to the target. 


A null string gives the value zero; a string of blanks is invalid. 


BIT © 
If the conversion occurs during evaluation of an operational expression, the 
- source bit string is converted to an unsigned value that is FIXED BIN(M,0) See 
the specific target types of coded arithmetic data using FIXED BINARY as the 
source. 
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Source-to-target rules 


If the source string is longer than the allowable precision, bits on the left are 
ignored. If nonzero bits are lost, the SIZE condition is raised. 


A null string gives the value zero. 


GRAPHIC 
Graphic variables and strings are converted to CHARACTER, and then follow 
the rules for character source described on page 77. 


Target: FIXED BINARY (p2,q2) 


Source: 


FIXED DECIMAL (p1,q1) 
The precision of the result is p2 = min(N,1+CEIL(p1*3.32)) and 
q2=CEIL(ABS(q1*3.32))*SIGN(q1). 


FLOAT BINARY (p1) 
The precision conversion is as described under “Converting arithmetic precision” 
on page 75 with p1 as declared or indicated and q1 as indicated by the binary 
point position and modified by the value of the exponent. 


FLOAT DECIMAL (p1) 
The precision conversion is the same as for FIXED DECIMAL to FIXED 
BINARY with p1 as declared or indicated and q1 as indicated by the decimal 
point position and modified by the value of the exponent. 


Arithmetic character PICTURE 
CHARACTER 
BIT 
GRAPHIC 
See Target: Coded Arithmetic on page 77. 


| Target: FIXED DECIMAL (p2,q2) 


Source: 


FIXED BINARY (p1,q1) 
The precision of the result is p2=1+CEIL(p1/3.32) and 
q2=CEIL(ABS(q1/3.32))*SIGN(q1). 


FLOAT BINARY (p1) 
The precision conversion is the same as for FIXED BINARY to FIXED 
DECIMAL with p1 as declared or indicated and q1 as indicated by the binary 
point position and modified by the value of the exponent. 


FLOAT DECIMAL (p1) 
The precision conversion is as described under “Converting arithmetic precision” 
on page 75 with p1 as declared or indicated and q1 as indicated by the decimal 
point position and modified by the value of the exponent. 
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Arithmetic character PICTURE 
CHARACTER 
BIT 
GRAPHIC 
See Target: Coded Arithmetic on page 77. 


Target: FLOAT BINARY (p2) 


Source: 


FIXED BINARY (p1,q1) 
The precision of the result is p2=p1. The exponent indicates any fractional part 
of the value. 


FIXED DECIMAL (p1,q1) 
The precision of the result is p2=CEIL(p1*3.32). The exponent indicates any 
fractional part of the value. 


FLOAT DECIMAL (p1) 
The precision of the result is p2=CEIL(p1*3.32). 


Arithmetic character PICTURE 
CHARACTER 
BIT 
GRAPHIC 
See Target: Coded Arithmetic on page 77. 


Target: FLOAT DECIMAL (p2) 


Source: 


FIXED BINARY (p1,q1) 
The precision of the result is p2=CEIL(p1/3.32). The exponent indicates any 
fractional part of the value. 


FIXED DECIMAL (p1,q1) 
The precision of the result is p2=p1. The exponent indicates any fractional part 
of the value. 


FLOAT BINARY (p1) 
The precision of the result is p2=CEIL(p1/3.32). 


Arithmetic character PICTURE 
CHARACTER 
BIT 
GRAPHIC 
See Target: Coded Arithmetic on page 77. 
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Source-to-target rules 


Target: Arithmetic character PICTURE 


The arithmetic character PICTURE data item is the character representation of a 
decimal fixed-point or floating-point value. The following descriptions for source to 
arithmetic character PICTURE target show those target attributes that allow assign- 
ment without loss of leftmost or rightmost digits. 


Source: 
FIXED BINARY (p1,q1) 
The target must imply: 


fixed decimal (1+xtq-y,q) or 
float decimal (x) 


where x>=CEIL(p1/3.32), y=CEIL(q1/3.32), and q>=y. 
FIXED DECIMAL (p1,q1) 
The target must imply: 


fixed decimal (xtq-ql,q) or 
float decimal (x) 


where x>=p1 and q>=q1. 
FLOAT BINARY (p1) 
The target must imply: 


fixed decimal (p,q) or 
float decimal (p) 


where p>=CEIL(p1/3.32) and the values of p and q take account of the range of 
values that can be held by the exponent of the source. 


FLOAT DECIMAL (p1) 
The target must imply: 


fixed decimal (p,q) or 
float decimal (p) 


where p>= pi and the values of p and q take account of the range of values 
that can be held by the exponent of the source. 


Arithmetic character PICTURE 
The implied attributes of the source will be either FIXED DECIMAL or FLOAT 
DECIMAL. See the respective entries for this target. 


CHARACTER 
See Target: Coded Arithmetic on page 77. 


BIT(n) 
The target must imply: 


fixed decimal (1+xtq,q) or 
float decimal (x) 


where x>=ceil(n/3.32) and q>=0. 


GRAPHIC 
See Target: Coded Arithmetic on page 77. 
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| Target: CHARACTER | 


Source: 


FIXED BINARY, FIXED DECIMAL, 

FLOAT BINARY, and FLOAT DECIMAL 
The coded arithmetic value is converted to a decimal constant (preceded by a 
minus sign if it is negative) as described below. The constant is inserted into an 
intermediate character string whose length is derived from the attributes of the 
source. The intermediate string is assigned to the target according to the rules 
for string assignment. 


The rules for coded-arithmetic-to-character-string conversion are also used for 
list-directed and data-directed output, and for evaluating keys (even for 
REGIONAL files). 


FIXED BINARY (p1,q1) 
The binary precision (p1,q1) is first converted to the equivalent decimal preci- 
sion (p,q), where p=1+CEIL(p1/3.32) and q=CEIL(ABS(q1/3.32))*SIGN(q1). 
Thereafter, the rules are the same as for FIXED DECIMAL to CHARACTER. 


FIXED DECIMAL (p1,q1) 
If p1>=qi>=0 then: 


* The constant is right adjusted in a field of width p1+3. (The 3 is necessary 
to allow for the possibility of a minus sign, a decimal or binary point, and a 
leading zero before the point.) 


°® Leading zeros are replaced by blanks, except for a single zero that imme- 
diately precedes the decimal point of a fractional number. A single zero 
also remains when the value of the source is zero. 


* A minus sign precedes the first digit of a negative number. A positive value 
is unsigned. 


* If q1=0, no decimal point appears; if q1>0, a decimal point appears and the 
constant has q fractional digits. 


If p1<qi or qi<0, a scaling factor appends to the right of the constant; the con- 
stant is an optionally-signed integer. The scaling factor appears even if the 
value of the item is zero. The scaling factor has the syntax: 


F{+l=}nn 
where {+l-}nnn has the value of -q1. 


The length of the intermediate string is p1+k+3, where k is the number of digits 
necessary to hold the value of qi (not including the sign or the letter F). 


If the arithmetic value is complex, the intermediate string consists of the imagi- 
nary part concatenated to the real part. The left-hand, or real, part is generated 
as a real source. The right-hand, or imaginary, part is always signed, and it has 
the letter | appended. The generated string is a complex expression with no 
blanks between its elements. The length of the intermediate string is: 

ree Maar for pl>=ql>=0 

2*(pl+k)+7 for pl>ql or ql>0 
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Source-to-target rules 


The following examples show the intermediate strings that are generated from 
several real and complex fixed-point decimal values: 


Precision Value String 

(5,0) 2947 "pbdb2947' 
(4,1) “AL ay iw gel ee 
(4,-3) -3279000 '-3279F+3' 
CZa1) 1.2+0.31 'ppb1.2+0.31' 


FLOAT BINARY (p1) 
The floating-point binary precision (p1) first converts to the equivalent floating- 
point decimal precision (p), where p=CEIL(p1/3.32). Thereafter, the rules are 
the same as for FLOAT DECIMAL to CHARACTER. 


FLOAT DECIMAL (p1) 
A decimal floating-point source converts as if it were transmitted by an E-format 
item of the form E(w,d,s) where: 


w, the length of the intermediate string, is pl+6. 
d, the number of fractional digits, is pl-l. 


s, the number of significant digits, is pl. 


If the arithmetic value is complex, the intermediate string consists of the imagi- 
nary part concatenated to the real part. The left-hand, or real, part is generated 
as a real source. The right-hand, or imaginary, part is always signed, and it has 
the letter | appended. The generated string is a complex expression with no 
blanks between its elements. The length of the intermediate string is 2*p+13. 


The following examples show the intermediate strings that are generated from 
several real and complex floating-point decimal values: 


Precision Value String 

(5) 1735" 10**5 'D1.7350E+08' 

(5) - 001663 "-1.6630E-03' 

(3) 1 "1 QGE+00' 

(5) 17,341.51 'D1.7300E+01+1.5000E+001' 


Arithmetic character PICTURE 
A real arithmetic character field is interpreted as a character string and assigned 
to the target string according to the rules for converting string lengths. If the 
arithmetic character field is complex, the real and imaginary parts are concat- 
enated before assignment to the target string. Insertion characters are included 
in the target string. 


BIT 
Bit O becomes the character 0 and bit 1 becomes the character 1. A null bit 
string becomes a null character string. The generated character string is 
assigned to the target string according to the rules for converting string lengths. 
GRAPHIC 


DBCS to SBCS conversion is possible only if there is a corresponding SBCS 
character. Otherwise, a CONVERSION condition is raised. 
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Source-to-target rules 


| Target: BIT | 


Source: 


FIXED BINARY, FIXED DECIMAL, 

FLOAT BINARY, and FLOAT DECIMAL 
If necessary, the arithmetic value converts to binary and both the sign and any 
fractional part are ignored. (If the arithmetic value is complex, the imaginary 
part is also ignored.) The resulting binary value is treated as a bit string. It is 
assigned to the target according to the rules for string assignment. 


FIXED BINARY (p1,q1) 
The length of the intermediate bit string is given by: 


min(n, (pl-ql)) 
If (p1-q1) is negative or zero, the result is a null bit string. 


The following examples show the intermediate strings that are generated from 
several fixed-point binary values: 


Precision Value String 


(1) 1 AD 
(3) =3 "O11'B 
(4,2) 1225 "O1'B 


FIXED DECIMAL (p1,q1) 
The length of the intermediate bit string is given by: 


min(n, CEIL((pl-q1)*3.32)) 

If (p1-q1) is negative or zero, the result is a null bit string. 

The following examples show the intermediate strings that are generated from | 
several fixed-point decimal values: 

Precision Value String 


(1) 1 "0001'B 
(24) Soi "Q001'B 


FLOAT BINARY (p1) 
The length of the intermediate bit string is given by: 


min(n,pl) 


FLOAT DECIMAL (p1) 
The length of the intermediate bit string is given by: 


min(n, cei l(p1*3.32)) 


Arithmetic character PICTURE 
Data is first interpreted as decimal with scale and precision determined by the 
corresponding PICTURE specification. The item then converts according to the 
rules given for FIXED DECIMAL or FLOAT DECIMAL to BIT. 


CHARACTER 
Character 0 becomes bit 0 and character 1 becomes bit 1. Any character other 
than O or 1 raises the CONVERSION condition. A null string becomes a null bit 
string. The generated bit string, which has the same length as the source char- 
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Examples 


acter string, is assigned to the target according to the rules for string assign- 
ment. 


GRAPHIC 7 
Graphic variables and strings are converted to CHARACTER, and then follow 
the rules for character source described on page 83. 


Target: GRAPHIC 


Nongraphic source is first converted to character according to the rules in Target: 
Character on page 81. The resultant character string is then converted to a DBCS 
string. 


Examples 


DECIMAL FIXED to BINARY FIXED with fractions 


del I fixed bin(31,5) init(1); 
I = I4+.1; 


The value of | is now 1.0625. This is because .1 is converted to FIXED 

BINARY (5,4), so that the nearest binary approximation is 0.0001B (no rounding 
occurs). The decimal equivalent of this is .0625. The result achieved by specifying 
.1000 in place of .1 would be different. 


Arithmetic-to-bit-string conversion 
DCL A bit(1), 
D DIteS)s 
: /* A has value 'Q'B */ 
: /* D has value '0Q010'B */ 
1 Bs /* D has value '10000'B */ 
A=l then go to Y; 
else go to X; 


toll 


A=] 
Dal 
D=' 


tT 


The branch is to X, because the assignment to A resulted in the following sequence 
of actions: 


1. The decimal constant, 1, has the attributes FIXED DECIMAL (1,0) and is 
assigned to temporary storage with the attributes FIXED BIN(4,0) and the value 
0001B. 


2. This value now converts to a bit string of length (4), so that it becomes 
‘0001 'B. 


3. The bit string is assigned to A. Since A has a declared length of 1, and the 
value to be assigned has acquired a length of 4, truncation occurs at the right, 
and A has a final value of '0'B. 


For the comparison operation in the IF statement, '0'B and 1 convert to FIXED 


BINARY and compared arithmetically. They are unequal, giving a result of fa/se for 
the relationship A=1. 
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In the first assignment to D, a sequence of actions similar to that described for A 
takes place, except that the value is extended at the right witn a zero, because D 
has a declared length that is 1 greater than that of the assigned value. 


Arithmetic-value-to-character-string conversion 
In the following example, the three blanks are necessary to allow for the possibility 
of a minus sign, a decimal or binary point, and provision for a single leading zero 
before the point: 
dcl A char(4), 
B char(7); 
A='0'; /*A has value ‘Obbb'*/ 
A=0;  /*A has value 'pdb0'*/ 
B=1234567; /*B has value 'bbp1234'*/ 


A conversion error 


dcl Ctlno char(8) init('0'); 
do I=1 to 100; 
Ctl no=Ctlnotl; 


end: 


For this example, FIXED DECIMAL precision 15 was used for the implementation 
maximum. The example raises the CONVERSION condition because of the fol- 
lowing sequence of actions: 


1. The initial value of CTLNO, that is, ‘OSpbbbbb' converts to FIXED 
DECIMAL(15,0). 


2. The decimal constant, 1, with attributes FIXED DECIMAL(1,0), is added; in 
accordance with the rules for addition, the precision of the result is (16,0). 


3. This value now converts to a character string of length 18 in preparation for the 
assignment back to CTLNO. 


_4. Because CTLNO has a length of 8, the assignment causes truncation at the 
right; thus, CTLNO has a final value that consists entirely of blanks. This value 
cannot be successfully converted to arithmetic type for the second iteration of 
the loop. 


Chapter 5. Dataconversion 85 


86 PL/I Package/2 Language Reference 





© Copyright IBM Corp. 1992 


Chapter 6. Program Organization 


Chapter 6. Program organization ......................... 89 
Programs” 46-4 go> 4h VED ane ee @ Dae ae ac & be oS ego Bok oe Bos 89 
Prodram:sttucture: 02:5 42 6B eee CARESS EGER a eM we eK 89 
PROGIAM-ACUVALION. fst g Sea chorale aces Ost ey SI ees a ee OS 90 
Program. termination. - 0. 6 x eck & face ie Be ee ee ee aS 90 
BIOCKS cack oe ce ere es At oe ae ee a ed a ee td A 91 
Block-activalion:: 52.5%: ob. ed Gmelin 20d a ee A Oe Ae We hie a 91 
BIOCKACIMINGUON 2.5 22%. ee & oe ee SS ee eS So BE oe 92 
PACKAGES): 8.509 eve Getic S ee ee Oe ee et os 2, 6 oe ee 92 
PACKAGE statement ...........0 00.000 2 cee ee 92 
PIOCGGUIOS: 1n.h cade S. oS m & Sed ak eae ee I ee ae 94 
PROCEDURE statement ................ 0.00000 0022s 94 
Parameter attribute 2... 2. 95 
Parameters and array arguments .................2.-00.- 96 
Procedure activation .........0.0.0 0.0000 pee 98 
Procedure termination ........0..0.0 20.000 eee ee 99 
Recursive procedures ...... 0.0.0.0... ce 100 
Effect of recursion on automatic variables ................. 101 
Dynamic loading of an external procedure ................... 101 
FUISS bats Oo shee oe ee dete tee hte Gr tt HS ee Bp & HE 102 
FETCH SIAlement?~ ibaio.ch Glee ah Lard ob Xe ee eee ee Gd 103 
RELEASE statement ................0. 02.00.0022 es 103 
SUDIOWUNES'~ =f ex 3 oh go ee Oo et Ae BEG © BE GE ae fe Se OM tele BOA 104 
Built-if SUBFOULINGS. % aos da se ea eho ey ee we ake Oe 106 
PUNICUOMS: -_ orca cave enn oc tay Gta ck 8. Ala Sb ty oe Bie bd ce, Oo GB ota Sul 106 
EXaMpleS® 4) ina 3 OM et hae eh se be Oe eR, Bd 107 
Built-in fUnClons: .:2-.06 3:5, Fe eS a eee Pe ae os ae Se 108 
Passing arguments to procedures .................000-0004. 108 
Using BYVALUE and BYADDR ................-.-.02050. 109 
DUMMY ArQUMeENMS.” <n eeh al hai BM R ee ea  e e  a s 109 
Deriving dummy argument attributes ..................0.. 109 
Rules for dummy arguments ................00+020000. 110 
Passing arguments to the MAIN procedure .................. 110 
BGG DIOCKS: © c.g od. ie Bt eR Maho 5) Sydnee Gee ee Pee Beg 111 
BEGIN statement: 4. 28 me eat nd ety eto bee oo ee eas eee 111 
Begin block activation .......... 0.0... 0.02 ee ee ee 111 
Begin block termination .............. 0.000022 111 
EMUY Odds enolic 5o sd oe eee a aa ee Be eee Ee oe 4 ae. es 112 
Entry constants ..............2...2204.% Nite oe Spire haga Erect 112 
ENUy VANADIOS ct) ocS SO eS SE OS ol GG ee Se 113 
ENTRY aunbUle 2. x fh ot Date Rhee oe ae Ha ko eae eg Sree 114 
OPTIONAL attribute ........ 0.2.0.0... 0.002 ee ee 116 
LIMITED AtHbUIe:. 66s §-5.2 Gh CSIR SG bE EEO SE Be, RES 117 
Genericentries 2.0.2... 0... . 000 118 
GENERIC attnbite: <2-< Ssh 4 se Soe a A Sets OS Se BE BS 118 
Entry invocation or entry value ........-...... 0.0.00 02.02. 0008, 120 
CALL cstatement:: .s.:h a Seo Oo a he 4 SE ee an Be bh ee ces 120 
RETURN statement ............ 00.0002 pe ee 121 
Return from a subroutine ......... 02.0200... ee ee 121 
Retum froma function: 2 <.< ae ee oe eke WO a ee a 121 


OPTIONS option and attribute 
RETURNS option and attribute 


88 PL/I Package/2 Language Reference 


Program organization 





Chapter 6. Program organization 


This chapter discusses how statements can be organized into different kinds of 
blocks to form a PL/I program, how control flows among blocks, and how different 
blocks can make use of the same data. 


Proper division of a program into blocks simplifies the writing and testing of the 
program, particularly when many programmers are writing it. Proper division can 
also result in more efficient use of storage, since automatic storage is allocated on 
entry to the block in which it is declared and released when the block is terminated. 


Programs 


Program structure 


PL/I is a block-oriented language, consisting of packages, procedures, begin 
blocks, statements, expressions, and built-in functions. 


A PL/I application consists of one or more separately loadable entities, known as a 
load module. An OS/2 load module has the file extension of EXE or DLL. Each 
load module may consist of one or more separately compiled entities, known as a 
compilation unit (CU). Unless otherwise stated, a program refers to a PL/I applica- 
tion or a compilation unit. 


A compilation unit is a PL/] PACKAGE or an external PROCEDURE. Each 
package may contain zero or more procedures, some or all of which may be 
exported. A PL/I external or internal procedure contains zero or more blocks. A 
PL/I block is either a PROCEDURE or a BEGIN block, which contains zero or more 
statements and/or zero or more blocks. 


A PL/I block allows you to produce highly-modular applications, because blocks can 
contain declarations that define variable names and storage class. Thus, you can 
restrict the scope of a variable to a single block or a group of blocks, or can make it 
known throughout the compilation unit or a load module. 


By giving you freedom to determine the degree to which a block is self-contained, 
PL/I makes it possible to produce blocks that many compilation units and applica- 


tions can share, leading to code reuse. 


Figure 24 on page 90 shows an application structure. 
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Program activitation 


Package External 
Procedure 


Compilation Level-1 Internal 
[Load Module] Unit Procedure Procedures 


Compilation Level-1 BEGIN Blocks 


Load Module | «——— Unit - Procedure 


Other 
Statements 





Figure 24. A PLA application structure 
Packages are discussed in “Packages” on page 92. 
Procedures are discussed in “Procedures” on page 94. 


Begin blocks are discussed in “Begin blocks” on page 111. 


Program activation 


A PL/I program becomes active when a calling program invokes the main proce- 
dure. This calling program usually is the operating system, although it could be 
another program. The main procedure is the external procedure for which the 
PROCEDURE statement has the OPTIONS(MAIN) specification. In the following 
example, Contr] is the main procedure and it invokes other external procedures in 
the program. The main procedure remains active for the duration of the program. 
Contr]: procedure options(main); 

call A; 

call B; 

call ¢; 
end contr1; 


Program termination 


A program is terminated when the main procedure is terminated. Whether termi- 
nation is normal or abnormal, control returns to the calling program. In the previous 
example, when control transfers from the C procedure back to the Contr1 proce- 
dure, Contr! terminates. See “Procedure termination” on page 99 for more infor- 
mation. 
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Blocks 


Blocks 


A block is a delimited sequence of statements that does the following: 
* Establishes the scope of names declared within it 
* Limits the allocation of automatic variables 


* Determines the scope of DEFAULT statements (as described in “Defaults for 
attributes” on page 141). 


The kinds of blocks are: 


* Package 
* Procedure 
° Begin. 


These blocks can contain declarations that are treated as local definitions of 
names. This is done to establish the scope of the names and to limit the allocation 
of automatic variables. These declarations are not Known outside their own block, 
and the names cannot be referred to in the containing block. See “Scope of 
declarations” for more information. 


Storage is allocated to automatic variables upon entry to the block where the 
storage is declared, and is freed upon exit from the block. See “Scope of 
declarations,” for more information. 


Block activation 


Each block plays the same role in the allocation and freeing of storage and in 
delimiting the scope of names. How activation occurs is discussed in “Procedures” 
on page 94 and “Begin blocks” on page 111. Packages are neither activated nor 
terminated. 


During block activation, the following are performed: 


* Expressions that appear in declare statements are evaluated for extents and 
initial values (including iteration factors). 

* Storage is allocated for automatic variables. Their initial values are set if speci- 
fied. 


* Storage is allocated for dummy arguments and compiler-created temporaries 
that might be created in this block. 


Initial values and extents for automatic variables must not depend on the values or 
extents of other automatic variables declared in the same block. For example, the 
following initialization can produce incorrect results for J and K: 


dcl I init(10).,J init(K),K init(1);: 


Declarations of data items must not be mutually interdependent. For example, the 
following declarations are invalid: 


del A(B(1)), BCAC1)); 
Gel. DCECI)),. “ECECL)).. 2eDCl)) 3 
Errors can occur during block activation, and the ERROR condition (or other condi- 


tions) can be raised. If so, the environment of the block might be incomplete. In 
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Block termination 


particular, some automatic variables might not have been allocated. Statements 
referencing automatic variables executed after the ERROR condition has been 
raised may reference unallocated storage. The results of referring to unallocated 
storage are undefined. 


Block termination 


There are a number of ways a block can be terminated. How termination occurs is 
discussed in “Procedures” on page 94 and “Begin blocks” on page 111. Packages 
are neither activated nor terminated. 


During block termination: 


® The ON-unit environment is re-established as it existed before the block was 
activated. 


* Storage for all automatic variables allocated in the block is released. 


Packages 


A package is a block that can only contain declarations, default statements, and 
procedure blocks. The package forms a name scope that is shared by all declara- 
tions and procedures contained in the package, unless the names are declared 
again. Some or all of the level 1 procedures can be exported and made known 
outside of the package as external procedures. A package can be used for imple- 
menting multiple entry point applications. 


PACKAGE statement 
The syntax for the PACKAGE statement is: 


aaa ae aay 
EXPORTS—(—¥-] dure Hl. 
(+O procedu ) 


aa ee declare-statement. 
options-option default-statement 
procedure -statement 













<4 


ea 
label -prefix 
procedure: 


t—procedure MC a Seep 
EXTERNAL ( environment -name) 


condition-prefix 
Condition prefixes specified on a PACKAGE statement apply to all procedures 
contained in the package unless overridden on the PROCEDURE statement. 
For more information on condition prefixes, refer to “Condition prefixes” on 
page 302. 


name 
The name of the package. 
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PACKAGE statement 


EXPORTS 
Specifies iat ali (EXPORTS(*)) or the named procedures are te be exported 
and thus made externally known outside of the package. 


procedure name 
Is the name of a level 1 procedure within the package. 


EXTERNAL (environment name) 
is a scope attribute discussed in “Scope of declarations” on page 132. 


options option 
For OPTIONS options applicable to a package statement, refer to “OPTIONS 
option and attribute” on page 121. 


declare statement 
All variables declared within a package but outside any contained level 1 proce- 
dure must have the storage class of static, based, or controlled. Automatic 
variables are not allowed. Default storage class is STATIC. Refer to 
Chapter 7, “Data declaration” on page 128. 


default statement 
Refer to “Defaults for attributes’ on page 141. 


procedure statement 
Refer to “PROCEDURE statement’ on page 94. 


An example of the package statement appears in Figure 25. 


*Process S ACF) LANGLVL(SAA2) LIMITSCEXTNAME(31)) NUMBER; 
Package_Demo: Package exports (Factorial); 


[BRK R IK ERIK IKK IKI KAIRIE IK IIIA IK IK HIKARI AIK IR 


[* Common Data sy f 
KKKKKEKKKKKKKEKKEKKK KEK KKK KEKE KKK KKK KKKEKKEKKEKKEKKK 
/ 


Del n fixed bin(15); 
Dcl message char(*) value('The factorial of '); 


[RRKKRKEKKK EKER KEK AKER EKER KKK RK KEK KAEKRKKIK ER | 


isi Main Program x 
[ BRRRRKREKE KKK KER KK KK AK RK KKK KIKI K KKK AKER ERE | 


Factorial: Proc Options (main); 


Del result fixed bin(31); 


put skip list('Please enter a number whose factorial ' || 
‘must be computed '); 


get list(n); 
result = Compute_factorial(n); 
put list(message I! trim(n) Il * is ' Il trim(result)); 


end Factorial; 





Figure 25 (Part 1 of 2). Package statement 
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Procedures 


[BRKRRRKKKKR KKK RAK KKK KKK KKK KIRK KKK KEK AKKREKAKE | 


/* Subroutine */ 
[BE RRRKRKK KKK RK KKK ERK IRRRKEAK RARER | 


Compute_factorial: proc (input) recursive returns (fixed bin(31)); 


dcl input fixed bin(15); 


if input <= 1 then 
return(1); 
else 
return( input*Compute_factorial(input-1) ); 


end Compute_factorial; 


end Package_Demo; 





Figure 25 (Part 2 of 2). Package statement 


Procedures 


A procedure is a sequence of statements delimited by a PROCEDURE statement 
and a corresponding END statement. A procedure can be a main procedure, a sub- 
routine, or a function. An application must have exactly one external procedure 
that has OPTIONS(MAIN). In the following example, the name of the procedure is 
Name and represents the entry point of the procedure. 

Name: 


procedure; 
end Name; 


A procedure must have a name. A procedure block nested within another proce- 
dure or begin block is called an internal procedure. A procedure block not nested 
within another procedure or begin block is called an external procedure. Level 1 
exported procedures from a package also become external procedures. External 
procedures can be invoked by cine? procedures in other Compilation units. Proce- 
dures can invoke other procedures. 


A procedure can be recursive, which means that it can be reactivated from within 
itself or from within another active procedure while it is already active. You can 
pass arguments when invoking a procedure. 


For more information on these subjects, see the following sections: 


“Scope of declarations” on page 132 
“Subroutines” on page 104 

“Functions” on page 106 

“Passing arguments to procedures” on page 108. 


PROCEDURE statement 


A procedure statement identifies the procedure as a main procedure, a subroutine, 
or a function. Parameters expected by the procedure and other characteristics are 
also specified on the procedure statement. 
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Parameter attribute 


The syntax for the PROCEDURE statement is: 


pp>—entry-labe]:—PROCEDURE 
: returns -optio 
(+ parameter_L) 


> eee 
L options -option] Lrecursion-attribute L externa ] attribute 


END $———__—_—————— > 
LC enery aber 





Abbreviations: PROC for PROCEDURE 


entry-label 
Is the entry point to the procedure. External entries are explicitly declared 
in the invoking procedure. Refer to “Entry data” on page 112 for more 
information. 


parameter 
Refer to “Parameter attribute” and “Passing arguments to procedures” on 
page 108. 


returns-option 
applies only to function procedures. Refer to “Functions” on page 106 
and “RETURNS option and attribute” on page 126 


options-option 
Refer to “OPTIONS option and attribute” on page 121. 


recursion-attribute . 
Refer to “Recursive procedures” on page 100. 


external-attribute 
Refer to “Scope of declarations” on page 132. 


Parameter attribute 


A parameter is contextually declared with the parameter attribute by its specification 
in the PROCEDURE statement. The parameter should be explicitly declared with 
appropriate attributes. The PARAMETER attribute may also be specified in the dec- 
laration. If attributes are not supplied ina DECLARE statement, default attributes 
are applied. The parameter name must not be subscripted or qualified. 


The syntax of the parameter attribute is: 


>> —PARAME TERA Ap 


Figure 10 on page 29, and the following discussion, describe the attributes that 
can be declared for a parameter. 


A parameter always has the INTERNAL attribute. 


lf the parameter is a structure or union, it must specify the level-1 name. 
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Parameter attribute 


A parameter cannot have any storage class attributes except CONTROLLED. A 
controlled parameter must have a controlled argument, and can also have the 
INITIAL attribute. 


Parameters used in record-oriented input/output, or as the base variable for 
DEFINED items, must be in connected storage. The CONNECTED attribute must 
be specified both in the declaration in the procedure and in the descriptor list of the 
procedure entry declaration. 


Parameters and array arguments 

If an argument is an array, a string, or an area, the bounds of the array, the length 
of the string, or the size of the area must be declared for the corresponding param- 
eter. The number of dimensions and the bounds of an array parameter, or the size 
and length of an area or string parameter, must be the same as the current gener- 
ation of the corresponding argument. 


Noncontrolled parameter extents: Extents of noncontrolled parameters must be 
specified either by asterisks or by constants. When the actual extents could be 
different for different occasions, each can be specified in a DECLARE statement by 
an asterisk. When an asterisk is used, the extents are taken from the current gen- 
eration of the associated argument. 


Controlled parameter extents: The extents of a controlled parameter can be 
specified in a DECLARE statement either by asterisks or by element expressions. 


Asterisk notation When asterisks are used, extents of the controlled parameter 
is taken from the current generation of the associated argu- 
ment. Any subsequent allocation of the controlled parameter 
uses the same extents. Unless the argument in the calling 
procedure is a controlled parameter, it must be declared with 
nonresiricted expressions for its extents. 


Expression notation 
Each time the parameter is allocated, the expressions are 
evaluated to give current extents for the new allocation. 


Example of array argument with parameters: \|n Figure 26 on page 97, when 
Subl is invoked, A and B, which have been allocated, are passed. 
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Parameter attribute 


aprocess or('l') num marains(1,72): 


Package:package exports(*); 














































Main: procedure options(Main); 
declare (A(NA), BCNB), CCNC), D(ND) ) controlled; 
declare (NA init(20), NB init(30), NC init(100), 
ND init(100) ) fixed bin(31); 
declare Subl entry((*) controlled, (*) controlled); 
declare Sub2 entry ((*) ctl, (*) ctl, fixed bin); 
allocate A,B; /* a(20), b(30) */ 


display ('Genl: DIM(A)=" 11 dim(a) Il ', ' }1 “DIM(B)=" 11 dim(b)); 
call Subl1(A,B); 
display ('Gen2: Allocn(A)=' || allocn(a) Il ‘', ‘ Tl 
‘Allocn(B)=' || allocn(b) ); 
display ('Gen2: DIM(A)=' || dim(a) 11 ', ' Il “DIM(B)=" 11 dim(b)); 
free A,B; 
display ('Genl: Allocn(A)=' |! allocn(a) Il ', * UI 
"Allocn(B)=' |! allocn(b) ); 
display ('Genl: DIM(A)=' || dim(a) Il ', ' tl "DIM(B)=" 11 dim(b)); 
free A,B; 
display ('GenO: Allocn(A)=' I! allocn(a) Il ', * JI 
"Allocn(B)=' {1 allocn(b) ); 
call Sub2 (C,D,10); 
display ('Genl: Allocn(C)=" || allocn(c) Il *, ' JI 
"Allocn(D)=' 11 allocn(d) ); 
display ('Genl: DIM(C)=' || dim(c) Il ', ' Tl "DIM(D)="_ 11 dim(d)); 
free C,D; 
display ('GenO: Allocn(C)=" I! allocn(c) Il ', ' | 
‘Allocn(D)=' || allocn(d) ); 
end Main; 


Subl: procedure (U,V); 
del (UCUB), V(*)) controlled, 
UB fixed bin(31); 


display ('Genl: Allocn(U)=' I! allocn(u) Tl’, ' UI 
‘Allocn(V)=' || allocn(v) ); 
display ('Genl: DIMCU)=" 11 dim(u) Il *, ° Tf "DIM(V)=" Tt dim(v)); 
UB=200; 
allocate U,V; /* u(200), v(30) */ 
display ('Gen2: Allocn(U)=' II allocn(u) Il ‘, * II 
"Allocn(V)=' || allocn(v) ); 
display ('Gen2: DIM(U)=" 11 dim(u) Il ', * Tl “DIM(V)="_ 11 dim(v)); 
end Subl; 


Sub2: procedure (X,Y,N); 
declare (X(N),YCN)) controlled, 
N fixed bin; 
display ('Gen@: Allocn(X)=' 11 allocn(x) I! ', ' I 
‘Allocn(Y)=' Il allocn(y) ); 
allocate X,Y; /* x(10), y(10) */ 
display ('Genl: Allocn(X)=" II allocn(x) I! ', * II 
"Allocn(Y)=" I! allocn(y) ); 
display (‘Genl: DIM(X)=' Il dim(x) 1! ', ' Tl "DIM(Y)=" 11 dim(y)); 
end Sub2; 


end Package; 


Figure 26. Array argument with parameters 


The ALLOCATE statement in Sub1 allocates a second generation of Aand B. 8B has 
the same bounds for both generations, and A has different bounds for the second 
generation. 


On return to Main, the first FREE statement frees the second generation of A and B 
(allocated in Sub1). The second FREE statement frees the first generation of A and 
B (allocated in Main). 


In Sub2, X and Y are declared with bounds that depend on the value of N. When xX 
and Y are allocated, their values determine the bounds of the allocated arrays. 
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On return to Main from Sub2, the FREE statement frees the only generation of C and 
D (allocated in Sub2). 


Procedure activation 
Sequential program flow passes around a procedure, from the statement before the 
PROCEDURE statement to the statement after the END statement of that proce- 
dure. The only way that a procedure can be activated is by a procedure reference. 
(“Program activation” on page 90 tells how to activate the main procedure.) The 
execution of the invoking procedure is suspended until the invoked procedure 
returns control to it. 


A procedure reference is the appearance of an entry expression in one of the fol- 
lowing contexts: 


* Using a CALL statement to invoke a subroutine as described in “CALL 
statement.” 


* Invoking a function as described in “Functions.” 


The information in this section is relevant to each of these contexts. However, the 
examples in this chapter use CALL statements. 


When a procedure reference occurs, the procedure containing the specified entry 
point is said to be invoked. The point at which the procedure reference appears is 
called the point of invocation and the block in which the reference is made is called 
the invoking block. An invoking block remains active even though control is trans- 
ferred from it to the procedure it invokes. 


When a procedure is invoked, arguments and parameters are associated and exe- 
cution begins with the first statement in the invoked procedure. 


This procedure: 


Readin: procedure; 
statement -1 
statement-2 
statement -3 


end readin; 
can be activated by this entry reference: 
call Readin; 


The entry constant (Readin) can also be assigned to an entry variable that is used 
in a procedure reference. For example: 


declare Readin entry, 
Entl entry variable; 
Entl = Readin; 
call] Entl; 
call Readin; 


The two CALL statements have the same effect. 
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Procedure termination 


A procedure is terminated when, by some means other than a procedure reference, 
control passes back to the invoking program, block, or to some other active block. 


Procedures normally terminate when: 


Control reaches a RETURN statement within the procedure. The execution of 
a RETURN statement returns control to the point of invocation in the invoking 
procedure. lf the point of invocation is a CALL statement, execution in the 
invoking procedure resumes with the statement following the CALL. If the point 
of invocation is a function reference, execution of the statement containing the 
reference is resumed. 


Control reaches the END statement of the procedure. Effectively, this is equiv- 
alent to the execution of a RETURN statement. 


Procedures abnormally terminate when: 


Control reaches a GO TO statement that transfers control out of the procedure. 
The GO TO statement can specify a label in a containing block, or it can 
specify a parameter that has been associated with a label argument passed to 
the procedure. 


A STOP statement is executed. 
An EXIT statement is executed. 


The ERROR condition is raised and there is no established ON-unit for ERROR 
or FINISH. Also, if one or both of the conditions has an established ON-unit, 
ON-unit exit is by normal return, rather than by a GO TO statement. 


The procedure calls or invokes another procedure that terminates abnormally. 


Transferring control out of a procedure using a GO TO statement can sometimes 
result in the termination of several procedures and/or begin-blocks. Specifically, if 
the transfer point specified by the GO TO statement is contained in a block that did 
not directly activate the block being terminated, all intervening blocks in the acti- 
vation sequence are terminated. 
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In the following example: 


A: procedure options(main); 
statement -1 
statement -2 
B: begin; 

Statement -bl 
Statement -b2 
call C; 
Statement -b3 
end B; 
statement -3 
statement -4 
C: procedure; 
Statement -cl 
Statement -c2 
Statement -c3 
D: begin; 
statement-dl 
statement -d2 
go to Lab; 
statement -d3 
end D; 
statement -c4 
end C; 
statement -5 

Lab: statement-6 
statement -7 

end A; 


A activates B, which activates C, which activates D. In D, the statement go to Lab 
transfers control to statement-6 in A. Since this statement is not contained in D, C, 
or B, all three blocks are terminated; A remains active. Thus, the transfer of control 
out of D results in the termination of intervening blocks B and C as well as the termi- 
nation of block D. 


Recursive procedures 
n 


An active procedure that is invoked from within itself or from within another active 
procedure is a recursive procedure. Such an invocation is called recursion. 


A procedure that is invoked recursively must have the RECURSIVE attribute speci- 
fied in the PROCEDURE statement. The syntax for the RECURSIVE attribute is 
shown in “PROCEDURE statement” on page 94. 


The environment (that is, values of automatic variables, and so on) of every invoca- 
tion of a recursive procedure is. preserved in a manner analogous to the stacking of 
allocations of a controlled variable (see “Controlled storage and attribute” on 

page 201). Think of an environment as being pushed down at a recursive invoca- 
tion, and popped up at the termination of that invocation. A label constant in the 
current block is always a reference to the current invocation of the block that con- 
tains the label. 


If a label constant is assigned to a label variable in a particular invocation, and the 
label variable is not declared within the recursive procedure, a GO TO statement 
naming that variable in another invocation restores the environment that existed 
when the assignment was performed, terminating the current and any intervening 
procedures and begin blocks. 
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The environment of a procedure that was invoked from within a recursive procedure 
by means of an eniry variabie is ihe one ihai was curreni wiien the entry constant 
was assigned to the variable. Consider the following example: 

I=1; 

call A; _ /* First invocation of A ai 


A: proc recursive; 
declare Ev entry variable static; 
if I=1 then 
do; 
I=2; 
Ev=B; 
call A; /* 2nd invocation of A xf 
end; 
else call Ev; /* Invokes B with environment */ 
/* of first invocation of A */ 
Bs procs 
go to Qut; 
end B; 
Out: end A; 


The GO TO statement in the procedure B transfers control to the END A statement in 
the first invocation of A, and terminates B and both invocations of A. 


Effect of recursion on automatic variables 
The values of variables allocated in one activation of a recursive procedure must be 
protected from change by other activations. This is arranged by stacking the vari- 
ables. A stack operates on a last-in, first-out basis. The most recent generation of 
an automatic variable is the only one that can be referenced. Static variables are 
not affected by recursion. Thus, they are useful for communication across recur- 
sive invocations. This also applies to automatic variables that are declared in a 
procedure that contains a recursive procedure and to controlled and based vari- 
ables. In the following example: 
A: proc; 

delxXs 


B: proc recursive; 
del :7,%; Statues 
call B; 


end B; 
end A; 
A single generation of the variable X exists throughout invocations of procedure B. 
The variable Z has a different generation for each invocation of procedure 8. The 
variable Y can be referred to only in procedure B and is not reallocated at each 
invocation. (The concept of stacking variables is also of importance in the dis- 
cussion of controlled variables in “Controlled storage and attribute” on page 201) 


Dynamic loading of an external procedure 


A DLL can be dynamically fetched (loaded) or released (deleted) by a PL/I program 
using FETCH and RELEASE statements. 


A procedure invoked by a procedure reference usually is resident in main storage 


throughout the execution of the program. However, a procedure can be loaded into 
main storage for only as long as it is required. The invoked procedure can be 
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dynamicaily loaded into, and dynamically deleted from, main storage during exe- 
cution of the calling procedure. 


Dynamic loading and deletion of procedures is particularly useful when a called pro- 
cedure is not necessarily invoked every time the calling procedure is executed, and 
when conservation of main storage is more important than a short execution time. 


The PL/I statements that initiate the loading and deletion of a procedure are 
FETCH and RELEASE statements respectively. 


The appearance of an entry constant in a FETCH statement indicates that the ref- 
erenced procedure needs to be loaded into main storage before it can be executed, 
unless a copy already exists in main storage. Provided the name is referenced in a 
FETCH statement, a procedure may also be loaded from the disk by: 


* Execution of a CALL statement or the CALL option of an INITIAL attribute 
* Execution of a function reference. 


It is not necessary that control passes through a FETCH or RELEASE statement, 
either before or after execution of the CALL or function reference. 


Whichever statement loaded the procedure, execution of the CALL statement or 
option or the function reference invokes the procedure in the normal way. 


It is not an error if the procedure has already been loaded into main storage. The 
fetched procedure can remain in main storage until execution of the whole program 
is completed. Alternatively, the storage it occupies can be freed for other purposes 
at any time by means of the RELEASE statement. 


Rules 
FETCH and RELEASE have the following restrictions: 


* Only external procedures can be fetched. 
* EXTERNAL CONDITION conditions are shared across the entire application 


(main and fetched modules). EXTERNAL files are shared in a iimiied way: 
— A FILE constant in an I/O statement (for example, OPEN, CLOSE READ, 
WRITE, PUT, or GET) is shared across the application. 


— Any FILE conditions (for example, ENDFILE), must be trapped in one 
linked unit. 


Other external variables are shared only within a single module. 


* A dynamic link library (DLL) contains one or more segments. Each segment 
contains one or more fetched procedures. A segment is loaded into memory 
when a procedure is fetched from a segment that is not already in memory. 
The memory will not be freed until all of the fetched procedures within a DLL 
have been released. 


* Storage for STATIC variables in the fetched procedure is allocated when the 
segment containing the procedure is loaded into memory. Each time a 
segment is loaded into memory, the STATIC variables are given the initial 
values indicated by their declarations. 


* The FETCH and RELEASE statements must specify entry constants. An entry 
constant for a fetched procedure may be assigned to an entry variable provided 
the procedure has been fetched. 
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FETCH statement 

The FETCH statement checks main storage tor the named procedures. froce- 
dures not already in main storage are loaded from the disk. COBOL, FORTRAN, 
or C routines cannot be fetched. The syntax for the FETCH statement is: 


mm FE Cpa)? 


cn eee tant 


SET( pointer-reference) TITLE( char-expr) 





entry-constant 
specifies the name by which the procedure to be fetched is known to the 
operating system. Details of the linking considerations for fetchable proce- 
dures are given in the PL/I Package/2 Programming Guide. 


The entry-constant must be the same as the one used in the corre- 
sponding CALL statement, CALL option, or function reference. 


SET SET specifies a pointer reference that will be set to the address of the 
entry point of the loaded module. This option can be used to load tables 
(non-executable load modules). It can also be used for entries that are 
fetched and whose address needs to be passed to non-PL/I procedures. 


If the load module is later released by the RELEASE statement, and the 
load module is accessed (through the pointer), unpredictable results can 
occur. 


TITLE If TITLE is specified, the load module name specified is searched for and 
loaded. If it is not specified, the load module name used is the environ- 
ment name specified in the EXTERNAL attribute for the variable (if 
present) or the entry constant name itself. For example: 


dcl-a entry; 
dcl b entry ext('C'); 


fetch a title('X'); /* X is loaded xf 
fetch a; /* A is loaded */ 
fetch b title('Y'); /* Y is loaded ica 
fetch b; /* C is loaded my 


For information on the types of title strings, refer to PL/I Package/2 Pro- 
gramming Guide. 


RELEASE statement 
The RELEASE statement frees the main storage occupied by procedures identified 
by its specified entry-constants. 


The syntax for the RELEASE statement is: 


vy RELEASE —S-antry-constant- bs — < 


entry-constant 
must be the same as the one used in the corresponding CALL statement, 
CALL option, or function reference, and FETCH statements. 
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Subroutines 


Consider the following example, in which ProgA and ProgB are entry names of pro- 
cedures resident on disk: 


Prog: procedure; 


A fetch ProgA; 

[2] call ProgA; 

ie | release ProgA; 

HI call ProgB; 
go to Fin; 


fetch ProgB; 
Fin: end Prog; 


[iJ | ProgA is loaded into main storage by the first FETCH statement 
2] ~ProgA executes when the first CALL statement is reached. 
[3] Storage for ProgA is released when the RELEASE statement is executed. 


HI. = ProgB is loaded and executed when the second CALL statement is reached, 
even though the FETCH statement referring to this procedure is never exe- 
cuted. 


The same results would be achieved if the statement FETCH ProgA were omitted. 
The appearance of ProgA in a RELEASE statement causes the statement CALL 
ProgA to load the procedure, as well as invoke it. 


The fetched procedure is compiled and linked separately from the calling proce- 
dure. You must ensure that the entry constant specified in FETCH, RELEASE, and 
CALL statements and options, and in function references, is the name known on 
the disk. This is discussed in your PL/I Package/2 Programming Guide. 


A subroutine is an internal or external procedure that is invoked by a CALL state- 
meni. The syntax for a subroutine is in “Procedures” on page 94. 


The arguments of the CALL statement are associated with the parameters of the 
invoked procedure. The subroutine is activated, and execution begins. The argu- 
ments (zero or more) can be input only, output only, or both. 


A subroutine is normally terminated by the RETURN or the END statement. 
Control is then returned to the invoking block. A subroutine can be abnormally 
terminated as described in “Procedure termination” on page 99. 
A subroutine procedure must: 

* Not have the RETURNS option on the procedure statement. 


* Not be declared as an entry with the RETURNS attribute if it is an external 
procedure. 


* Be invoked using the CALL statement, not a function reference. 
* Not return a result value using the RETURN statement. 


The following examples illustrate the invocation of subroutines that are internal to 
and external to the invoking block. 
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Example 1 


Prmain: procedure; 
declare Name character (20), 
Item bit(5), 


A Outsub entry; 
1 call outsub (Name, Item); 
end Prmain; 


2] = Outsub: procedure (A,B); 
declare A character (20), 
B bit(5); 
| put list (A,B); 
end Outsub; 


[| The CALL statement in Prmain invokes the procedure Outsub in ]2j with the 
arguments Name and Item. 


2] Outsub associates Name and Item passed from Prmain with its parameters, A 
and B. When Qutsub is executed, each reference to A is treated as a refer- 
ence to Name. Each reference to B is treated as a reference to Item. 


[3] The put list (A,B) statement transmits the values of Name and Item to the 
default output file, SYSPRINT. 


4] In the declaration of Outsub as an entry constant, no parameter descriptor has 
to be given with the ENTRY attribute, because the attributes of the arguments 
and parameters match. Also see “ENTRY attribute” on page 114. 


Example 2 


A: procedure; 
declare Rate float (10), 
Time float(5), 
Distance float(15), 
Master file; 


hy call Readcm (Rate, Time, Distance, Master); 
8 Readcm: 
| procedure (W,X,Y,Z); 
declare W float (10), 
X float(5), 


Y float(15), Z file; 

get File (Z) list (W,X,Y); 
Y = W*X; 
if Y > © then 

return; 
else 

put list('ERROR READCM' ); 
end Readcm; 


end A; 


[| The arguments Rate, Time, Distance, and Master are passed to the procedure 
Readcm in [B| and associated with the parameters W, X, Y, and Z. 


[2] A reference to W is the same as a reference to Rate, X the same as Time, Y the 
same as: Distance, and Z the same as Master. 


[3] Note that Readcm is not explicitly declared in A. It is implicitly declared with the 
ENTRY attribute by its specification on the PROCEDURE statement. 
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Functions 


Built-in subroutines 

You can use built-in subroutines, which provide ready-made programming tasks. 
Their built-in names can be explicitly declared with the BUILTIN attribute. (For 
more information on the BUILTIN attribute refer to “Declaring built-in functions” on 
page 377.) 


Each built-in subroutine is described in Chapter 17, “Built-in functions, 
pseudovariables, and subroutines.” 


A function is a procedure that has zero or more arguments and is invoked by a 
function reference in an expression. The function reference transfers control to a 
function procedure, and returns a value, and control, to replace the function refer- 
ence in the evaluation of the expression. Aggregates cannot be returned, and 
ENTRY variables cannot be returned unless they have the LIMITED attribute. The 
evaluation of the expression then continues. 


A function procedure must: 
* Have the RETURNS option on the procedure statement. 


* Be declared as an entry with the RETURNS attribute if it is an external proce- 
dure. 


* Be invoked using a function reference. The CALL statement can be used to 
invoke it only if the returned value has the OPTIONAL attribute. In this case, 
the returned value is discarded upon return. 


* Have matching attributes in the RETURNS option and in the RETURNS attri- 
bute. 


® Use the RETURN statement to return control and the result value. 


Whenever a function is invoked, the arguments in the invoking expression are 
associated with the parameters of the entry point. Control is then passed to that 
entry point. The function is activated and execution begins. 


The RETURN statement terminates a function and returns the value specified in its 
expression to the invoking expression. See “RETURN statement” on page 121 for 
more information. 


A function can be abnormally terminated as described in “Procedure termination” on 
page 99. If this method is used, evaluation of the expression that invoked the 
function is not completed, and control goes to the designated statement. 


In some instances, a function can be defined so that it does not require an argu- 
ment list. In such cases, the appearance of an external function name within an 
expression is recognized as a function reference only if the function name has been 
explicitly declared as an entry name. See “Entry invocation or entry value” on 

page 120 for additional information. 
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The following examples illustrate the invocation of functions that are internal to and 
external to the invoking block. 


Example 1: \|n the following example, the assignment statement contains a refer- 
ence to the Sprod function: 


Mainp: procedure; 
get list (A, B, C, Y); 
pl X = Y**34+SprodCa, B,C): 


12] = Sprod: procedure (U,V,W) 
returns (bin float(21)); 
del (U,V,W) bin float(53); 
if U> V + W then 


| return (Q); 
else 
| return (U*V*W) ; 
end Sprod; 


{{] When Sprod is invoked, the arguments A, B, and C are associated with the 
parameters U, V, and W in [2], respectively. 


[2] Sprod is a function because RETURNS appears in the procedure statement. 
It is internal, and therefore needs no explicit entry declaration. If Sprod were 
external, Mainp would contain an entry declaration with RETURNS specified. 


13] Sprod returns either O or the value represented by U*V*W, along with control to 
the expression in Mainp. The returned value is taken as the value of the func- 
tion reference, and evaluation of the expression continues. 


Example 2 


Mainp: procedure; 
dcl Tprod entry (bin float(53), 
bin float(53), 
bin float(53), 
label) external 
returns (bin float(21)); 
get list (A,B,.C,Y); 
pl X =. Y**3+Tprod(A,B.C, Labl): 
Labl: call Errt; 
end Mainp; 


[i] prod: procedure (U,V,W,Z) 
returns (bin float(21)); 
del (U,V,W) bin float(53); 
declare Z label; 


2 if U>V+W then 
go: to Z: 
Gl else 
return (U*V*W); 
end Tprod; 


[1] When Tprod is invoked, Lab1 is associated with parameter Z. 


[2] If Uis greater than V + W, control returns to Mainp at the statement labeled 
Labl. Evaluation of the assignment in [1] is discontinued. 


[3] If U is not greater than V + W, U*V*W is calculated and returned to Mainp in the 
normal fashion. Evaluation of the assignment in [lJ continues. 
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Notice that Tprod is an external procedure. It has an explicit entry declaration in 
Mainp, which contains RETURNS. 


Built-in functions 
Besides allowing programmer-written function procedures, PL/I provides a set of 
built-in functions. Built-in functions include commonly used arithmetic functions and 
others, such as functions for manipulating strings and arrays. Built-in functions are 
invoked in the same way that you invoke programmer-defined functions. However, 
many built-in functions can return an array of values, whereas a programmer- 
defined function can return only an element value. The built-in names for built-in 
functions can be explicitly declared with the BUILTIN attribute. (For more informa- 
tion on the BUILTIN attribute, refer to “Declaring built-in functions” on page 371.) 


Each built-in function is described in Chapter 17, “Built-in functions, 
pseudovariables, and subroutines.” 


Passing arguments to procedures 


When a function or a subroutine is invoked, parameters are associated, from left to 
right, with the passed arguments. The number of arguments and parameters must 
be the same. 


In general: 


* Computational data arguments can be passed to parameters of any computa- 
tional data type. 


* Program control data arguments must be passed to parameters of the same 
type, with these exceptions. 


— Pointer and offset can be passed to each other. 


— LIMITED ENTRY can be passed to ENTRY, but ENTRY cannot be passed 
to LIMITED ENTRY. 


— An array of label constants cannot be used as an argument. 


Arguments that require aggregate temporaries are not allowed. For example, the 
following statements are invalid as arguments if a, b, or c is an array. 


call X( cosa) ) 
call X( cos(btc) ) 


For example, instead of coding: 


dc] A(10) float bin(53), X entry; 
call X(cos{A)); 


you could code: 
dcl temp(hbound(A,1)) float bin(53); 


temp = cos(A); 
call X(temp); 


Expressions in the argument list are evaluated in the invoking block before the sub- 
routine or function is invoked. A parameter has no storage associated with it. It is 
merely a means of allowing the invoked procedure to access storage allocated in 
the invoking procedure. 


108 PL/ Package/2 Language Reference 


BYVALUE and BYADDR 


Using BYVALUE and BYADDR 


Unless an argument is passed BYVALUE, a reference to an argument, not its 
value, is generally passed to a subroutine or function. This is known as passing 
arguments by reference or BYADDR. A reference to a parameter in a procedure is 
a reference to the corresponding argument. Any change to the value of a param- 
eter is actually a change to the value of the corresponding argument. However, 
this is not always possible or desirable. Constants, for example, should not be 
altered by an invoked procedure. For arguments that should not change, a dummy 
argument containing the value of the original argument is passed. Any reference to 
the parameter then is a reference to the dummy argument and not to the original 
argument. 


Dummy arguments 
A dummy argument is created when the argument is any of the following: 


* A constant. 
* An expression with operators, parentheses, or function references. 


* A variable whose data attributes or alignment attributes or connected attribute 
are different from the attributes declared for the parameter. 


This does not apply to noncontroiled parameters when only bounds, lengths, or 
size differ and these are declared with asterisks 


This does not apply when an expression other than a constant is used to define 
the extents of a controlled parameter. In this case, argument and parameter 
extents are assumed to match. 


In the case of arguments and parameters with the PICTURE attribute, a 
dummy argument is created unless the picture specifications match exactly, 
after any repetition factors are applied. The only exception is that an argument 
or parameter with a + sign in a scaling factor matches a parameter or argument 
without the + sign. 


* Acontrolled string or area (because an ALLOCATE statement could change 
the length or extent). 


* A string or area with an adjustable length or size, associated with a noncon- 
trolled parameter whose length or size is a constant. 


Deriving dummy argument attributes 
PL/I derives the attributes of a dummy arguments as follows: 


* From the attributes declared for the associated parameter in an internal proce- 
dure. 


* From the attributes specified in the parameter descriptor for the associated 
parameter in the declaration of the external entry. If there was not a descriptor 
for this parameter, the attributes of the constant or expression are used. 


° From the extents (when specified by an asterisk in a declaration) of the argu- 
ment for the bounds of an array, the length of a string, or the size of an area. 
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Rules for dummy arguments 
The following rules apply to dummy arguments: 


* If a parameter is an element (that is, a variable that is neither a structure nor 
an array) the argument must be an element expression. 


°* When a VARYING string element is passed to a NONVARYING parameter, 
whose length is undefined (that is, specified by an asterisk), a dummy argu- 
ment with the current length of the original 


° Entry variables passed as arguments are assumed to be aligned, so that no 
dummy argument is created when only the alignments of argument and param- 
eter differ. See “Generic entries” on page 118, for a description of generic 
name arguments for entry parameters. 


° If the parameter is of the program control data type (except locator), the argu- 
ment must be a reference of the same data type. 


° If a parameter is a locator (pointer or offset), the argument must be a locator. 
If the types differ, a dummy argument is created. The parameter descriptor of 
an offset parameter must not specify an associated area. 


* A noncontrolled parameter can be associated with an argument of any storage 
class. However, if more than one generation of the argument exists, the 
parameter is associated only with that generation existing at the time of invoca- 
tion. 


° If the parameter is controlled, you must explicitly state this in the parameter 
descriptor for the ENTRY declaration. 


In addition, a controlled parameter must always have a corresponding con- 
trolled argument that cannot be subscripted, cannot be an element of a struc- 
ture, and cannot cause a dummy to be created. If more than one generation of 
the argument exists at the time of invocation, the parameter corresponds to the 
entire stack of generations in existence. Consequently, at the time of invoca- 
tion, a controlled parameter represents the current generation of the corre- 
sponding argument. A controlled parameter can be allocated and freed in the 
invoked procedure, allowing the manipulation of the allocation stack of the 
associated argument. 


If the extents of the controlled parameter are specified as asterisks or nonre- 
stricted expressions, the original declaration must have extents declared as 
nonrestricted expressions. 


Passing arguments to the MAIN procedure 
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The PROCEDURE statement for the main procedure can have a parameter list. 
Such parameters require no special considerations in PL/I. However, you must be 
aware of any requirements of the invoking program (for example, not to use a 
parameter as the target of an assignment). 


When the invoking program is the operating system, a single argument is passed to 
the program. If this facility is used, the parameter must be declared as a VARYING 
character string within the procedure. The current length is set equal to the argu- 
ment length at run-time. In the following example: 


Tom: proc (Param) options (main); 
del Param char(100) varying; 


storage is allocated only for the current length of the argument. 
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Begin blocks 


When the MAIN and NOEXECOPS options are specified, the main procedure can 
have a single parameter that is a VARYING CHARACTER siring. Tie parameter 
passes as is, and a descriptor is set up. (The slash (/) symbol, if contained in the 
string, is treated as part of the string). For example: 


main: proc(Parm) options(main noexecops ); 
dcl Parm char(n) varying; 


Begin blocks 


A begin block is a sequence of statements delimited by a BEGIN statement and a 
corresponding END statement. For example: 


B: begin; 
statement-1 
statement -2 


statement-n 
end B: 


BEGIN statement 


The BEGIN statement and a corresponding END statement delimit a begin block. 


The syntax for the BEGIN statement is: 


>>—BEGIN ; Sp 1 
Loptions -option 


options-option 
For the BEGIN block options, refer to “OPTIONS option and attribute” on 
page 121. 


Begin block activation 


Begin blocks are activated through sequential flow or as a unit in an IF, ON, 
WHEN, or OTHERWISE statement. 


You can transfer control to a labeled BEGIN statement by issuing the GO TO state- 
ment. 


Begin block termination 


A begin block is terminated when control passes to another active block by some 
means other than a procedure reference. The methods are: 


°* The END statement for the begin block is executed. Control continues with the 
statement physically following the END, except when the block is an ON-unit. 


* AGO TO statement within the begin block (or within any block internal to it) is 
executed. Control transfers to the point outside the block. 


® A STOP or an EXIT statement is executed. 


* Control reaches a RETURN statement that transfers control out of the begin 
block and out of its containing procedure. A RETURN statement in a begin 
block cannot contain an expression. 
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Entry data 


Entry data 


A GO TO statement can also terminate other blocks if the transfer point is con- 
tained in a block that did not directly activate the block being terminated. In this 
case, all intervening blocks in the activation sequence are terminated. For an 
example of this, see the example in “Procedure termination” on page 99. 


The entry data can be an entry constant or the value of an entry variable. 


An entry constant is a name prefixed to a PROCEDURE statement, or a name 
declared with the ENTRY attribute and not the VARIABLE attribute. It can be 
assigned to an entry variable. In the following example, P, £1, and £2 are entry 
constants. Ev is an entry variable. 

P: procedure; 


declare Ev entry variable, 
(E1,E2) entry; 


Ev = El; 
call Ev; 
Ev = E2; 
call Ev; 


The first CALL statement invokes the entry point E1. The second CALL invokes the 
entry point £2. 


The following example declares F(5), a subscripted entry variable. 


The five entries A, B, C, D, and E are each invoked with the parameters X, Y, and Z. 
declare (A,B,C,D,E) entry, 
declare F(5) entry variable initial (A,B,C,D,E); 
do I = 1 to 5; 
call FCI) (X,Y,2); 
end; 


When an eniry constant that is an entry point of an internal procedure is assigned 
to an entry variable, the assigned value remains valid only as long as the block that 
the entry constant was internal to remains active (and, for recursive procedures, 
remains current). 


Entry constants 


The appearance of a label prefix to a PROCEDURE statement explicitly declares 
an entry constant. A parameter-descriptor list is obtained from the parameter dec- 
larations, if any, and by defaults. 
External entry constants must be explicitly declared. This declaration: 

* Defines an entry point to an external procedure. 


* Optionally specifies a parameter-descriptor list (the number of parameters and 
their attributes), if any, for the entry point. 


* Specifies the attributes of the value that is returned by the procedure if the 
entry is a function. 
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Entry variables 


The syntax for an entry constant is: 


re Ow epee aera ieee 
(parameter-descriptor-list) RETURNS—attribut 


>» < 
Loptions( characteristic-list)— SEV TERNALCenu i ronmientenane)=. 





The attributes can appear in any order. 


ENTRY attribute 
For complete ENTRY attribute syntax, refer to “ENTRY attribute” on 
page 114. 


OPTIONS attribute 
For complete OPTIONS attribute syntax, refer to “OPTIONS option and 
attribute” on page 121. 


RETURNS attribute 
For complete RETURNS attribute syntax, refer to “RETURNS option and 
attribute” on page 126. 


EXTERNAL attribute 
For a complete description of the EXTERNAL attribute refer to “INTERNAL 
and EXTERNAL attributes” on page 134. 


Entry variables 


An entry variable can contain both interna! and external entry values. It can be part 
of an aggregate. For structuring and array dimension attributes, refer to “Arrays” on 
page 144 and “Structures” on page 147. 


The syntax for an entry variable is: 


>>—ENTRY 
(parameter-descriptor-list) OPTIONS( characteristic-1ist) 


>» 
LyaRTABLE— Li itep LReTURNS—attribute! 
2 eae eee ce te ee ee Se 
EXTERNAL( environment -name) 





The options can appear in any order. 


ENTRY attribute 
Refer to “ENTRY attribute” on page 114. 


OPTIONS attribute . 
Refer to “OPTIONS option and attribute” on page 121. 


VARIABLE attribute 
The VARIABLE attribute establishes the name as an entry variable. This 
variable can contain entry constants and variables. Refer to “VARIABLE 
attribute” on page 48 for syntax information. 


LIMITED attribute 
Refer to “LIMITED attribute” on page 117. 
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ENTRY 


RETURNS attribute 
Refer to “RETURNS option and attribute” on page 126. 


EXTERNAL attribute 
Refer to “Scope of declarations” on page 132. 


ENTRY attribute 


The ENTRY attribute specifies that the name being declared is either an external 
entry constant, or an entry variable. It also describes the attributes of the parame- 
ters of the entry point. 


The syntax for the ENTRY attribute is: 


>>—ENTRY 


SSS SST 
(44 parameter-descriptor --{ structure-union-descriptor ) 


parameter-descriptor: 





structure-union-descriptor: 


Pit ———_ 1 lever ———_]._________1 
attribut OPTIONAL attribute 


ENTRY The ENTRY attribute, without a parameter descriptor list, is implied by the 
RETURNS attribute. 





parameter-descriptor 
A parameter descriptor list can be given to describe the attributes of the 
parameters of the associated external entry constant or entry variable. It 
is used for argument and parameter attribute matching and the creation of 
dummy arguments. 


If no parameter descriptor list is given, the default is for the argument attri- 
butes to match the parameter attributes. Thus, the parameter descriptor 
list must be supplied if argument attributes do not match the parameter 
attributes. 


Each parameter descriptor corresponds to one parameter of the entry 
point invoked and, if given, specifies the attributes of that parameter. 


The parameter descriptors must appear in the same order as the parame- 
ters they describe. If a descriptor is absent, the default is for the argument 
to match the parameter. 
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ENTRY 


If a descriptor for a parameter is not required, the absence of the 
descriptor musi be indicaied by an asieiisk. For example: 


entry(character(10),*,*, fixed dec) Indicates four arguments. 





entry(*) Indicates one argument. 
entry( ) Specifies that the entry name must never 
have any arguments. 
entry Specifies that it can have any number of 
arguments. 
entry(float binary, *) Indicates two arguments. 
attribute 


The attributes can appear in any order in a parameter descriptor. For an 
array parameter-descriptor, the dimension attribute must be the first speci- 
fied. 


- An asterisk specifies that, for that parameter, any data type is allowed. 
The valid attributes following the asterisk are: 


°® ALIGNED or UNALIGNED 

* ASSIGNABLE or NONASSIGNABLE 
° BYADDR or BYVALUE 

* CONNECTED or NONCONNECTED 
* OPTIONAL 


No conversions will be done. 


OPTIONAL 
is discussed in “OPTIONAL attribute” on page 116. 


structure-union-descriptor 
For a structure union descriptor, the descriptor level numbers need not be 
the same as those of the parameter, but the structuring must be identical. 
The attributes for a particular level can appear in any order. 


Defaults are not applied if an asterisk is specified. For example, in the following 
declaration defaults are applied only for the second parameter. 


dcl X entry(* optional, aligned); /* defaults applied for 2nd parm */ 


Extents (lengths, sizes, and bounds) in parameter descriptors must be specified as 
constants or as asterisks. Controlled parameters must have asterisks. 
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OPTIONAL 


RETURNS attribute implies the ENTRY attribute. For example: 


Example parameter descriptors Declarations for example descriptors 
Test: procedure (A,B,C,D,E,F); declare Test entry 
(decimal fixed (5), 
declare A fixed decimal (5), binary float (21), 
B float binary (21), ei 
C pointer, Ts 
10; 25 
Aus ae 
2 Q, 3 decimal fixed, 
3 R fixed decimal, mS 
Le; (4) char(10)); 
2X; 
2 Y, 
Bulky 
F(4) character (10); 
end Test; 


In the previous example, the parameter C, and the structure parameter E do not 
have descriptors. 


OPTIONAL attribute 


OPTIONAL can be specified as part of the parameter-descriptor list or as an attri- 
bute in the parameter declaration. 


OPTIONAL arguments can be omitted in calls and function references by specifying 
an asterisk for the argument. An omitted item can be anywhere in the argument 
list, including at the end. However, the omitted item is counted as an argument. 
With its inclusion in an entry, the number of arguments must not exceed the 
maximum number allowed for the entry. 


Using OPTIONAL and BYVALUE for the same item is invalid. 


The receiving procedure can use the OMITTED built-in function to determine if an 
OPTIONAL parameter/argument was omitted in the invocation of the entry. (For 
more information on the OMITTED built-in function, refer to “OMITTED” on 

page 418.) 
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Figure 27 shows both valid and invalid CALL statements for the procedure Vrtn. 
Vrtn determines if OPTIONAL parameters were omitted, and takes the appropriate 
action. 


Caller: proc; 
dcl Vrtn entry ( 
fixed bin, 
ptr optional, 
float, 
* optional); 


/* The following calls are valid: */ 


call Vreintle; *, 15,5, “abed")s 
Cali Vetere, *,- 15.52%) 
call Vrtn(10, addr(x), 15.5, *); 


/* The following calls are invalid: */ 


Vrtn(10, addr(x), *, ‘display'); 
Vrtn(10, addr(x), 15.5); 

Vrtn(*, addr(x)); 
Vrtn(10,addr(x)); 

Vrtn(10); 

Vrtn; 

end Caller; 





Vetheproe Cebe Py -Fl,oGl)s 
dc] Fb fixed bin, 
P ptr optional, 
Fl float, 
Cl char(8) optional; 


if somitted(C1) then display (C1); 
if momitted(P) then P=P+10; 
end; 





Figure 27. Valid and invalid call statements 


LIMITED attribute 


The LIMITED attribute indicates that the entry variable will have only non-nested 
entry constants as values. A entry variable that is not LIMITED can have entry 
constants as values. 


A LIMITED static entry variable may be initialized with the value of a non-nested 
entry constant, thus permitting generation of more efficient code. It also uses less 
storage than a non-LIMITED entry variable. 


The syntax for the LIMITED attribute is: 


Dee ee 
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Example: 


Example: proc options(reorder reentrant); 
dcl (Read, Write) entry; 
dcl FuncRtn(2) entry limited 
static init (Read, Write); 


dcl (prtl) entry; 
dcl PrtRtn(2) entry variable limited 


stattc: Init: (Pred, /* legal * / 
Prt )e /* illegal */ 
Pri? proc: 
end prt2; 


end Example; 


Generic entries 


A generic entry declaration specifies a generic name for a set of entry references 
and their descriptors. During compilation, invocation of the generic name is 
replaced by one of the entries in the set. 


GENERIC attribute 


The generic name must be explicitly declared with the GENERIC attribute. 


The syntax for declaring generic entry data is: 


»>—generic-name—GENERIC—( AA _ > 


sans eee MOTT oer TT 


generic-descriptor 


Pe a er ee < 
»—entry-reference—OTHERWISE 


generic-descriptor: 


+—data-attributes 
LaLroneo— assienas.e—— [-covecreo—_ 
UNALIGNED NONASSIGNABLE—4 NONCONNECTED—4 
aa 
OPTIONAL 


Note: 
1 If specified, this keyword is ignored. 





Abbreviation: OTHER for OTHERWISE 


For the general declaration syntax, see page “DECLARE statement” on page 129. 


entry-reference 
must not be subscripted or defined. The same entry-reference can appear 
more than once within a single GENERIC declaration with different lists of 
descriptors. 


generic-descriptor . 
corresponds to a single argument. It specifies an attribute that the corre- 
sponding argument must have so that the associated entry reference can 
be selected for replacement. 
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GENERIC attribute 


Structures or unions cannot be specified. 


Where a descriptor is not required, its absence must be indicated by an 
asterisk. 


The descriptor that represents the absence of all arguments in the 
invoking statement is expressed by omitting the generic descriptor in the 
WHEN clause of the entry. It has the form: 


generic (... entryl when( ) ...) 


data-attributes 
The data attributes are listed in “Data types and attributes” on page 25. 


ALIGNED and UNALIGNED 
are discussed in “ALIGNED and UNALIGNED attributes” on page 139. 


ASSIGNABLE and NONASSIGNABLE 
are discussed in “ASSIGNABLE and NONASSIGNABLE attributes” on 
page 216. 


CONNECTED and NONCONNECTED 
are discussed in “CONNECTED and NONCONNECTED attributes” on 
page 217. 


OPTIONAL 
is discussed in “OPTIONAL attribute” on page 116. 


When an invocation of a generic name is encountered, the number of arguments 
specified in the invocation and their attributes are compared with descriptor list of 
each entry in the set. The first entry reference for which the descriptor list matches 
the arguments both in number and attributes replaces the generic name. 


In the following example, an entry reference that has exactly two descriptors with 
the attributes DECIMAL or FLOAT, and BINARY or FIXED is searched for. 


declare Calc generic ( 
Fxdcal when (fixed, fixed), 
Flocal when (float,float), 
Mixed when (float, fixed), 
Error otherwise); 
Decl X decimal float (6), 
Y binary fixed (15,0); 


Z = X+Calc(X,Y); 


If an entry with the exact number of descriptors with the exact attributes is not 
found, the entry with the OTHERWISE clause is selected if present. In the pre- 
vious example, Mixed is selected as the replacement. 


In a similar manner, an entry can be selected based on the dimensionality of the 
arguments. 


dc! D generic (D1 when ((*))), 
D2 when((*,*))), 


A(2), 

B(3,5); 
call D(A); /* Dl selected because A has one dimension */ 
call D(B); /* D2 selected because B has two dimensions */ 
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Entry invocation or entry value 


If all of the descriptors are omitted or consist of an asterisk, the first entry reference 
with the correct number of descriptors is selected. 


An entry expression used as an argument in a reference to a generic value only 
matches a descriptor of type ENTRY. If there is no such description, the program 
is in error. 


Entry invocation or entry value 


There are times when it may not be apparent whether an entry value itself will be 
used or the value returned by the entry invocation will be used. The following table 
and example help you understand which happens when. 


If the entry reference... Itis... 
Is a built-in function Invoked 
Has an argument list, even if null Invoked 
Is referenced in a CALL statement Invoked 
Has no argument list and is not refer- Not Invoked 


enced in a CALL statement 


In the following example, A is invoked, B(C) passes C as an entry value, and 
D( C() ) invokes C. 


del ( A, B, C returns (fixed bin), D) entry; 


call A; /* A is invoked */ 
call B(C); /* C iS passed as an entry value * | 
call D(C CC) ); /* C is invoked */ 


In the following example, the first assignment is invalid because it represents an 
attempt to assign an entry constant to an integer. The second assignment is valid. 


dc! A fixed bin, 
B entry returns ( fixed bin ); 


A = B; 
A= B(); 


CALL statement 


The CALL statement invokes a subroutine. 


The syntax for the CALL statement is: 


>>—CALL entry-referenc ( rr a | 
generi e-nane—] ie 
built-in-nam argument 
* 





entry-reference 
specifies that the name of the subroutine to be invoked is declared with 
the ENTRY attribute (discussed in “Entry data” on page 112). 
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RETURN 


generic-name 
specities that the name ot tne subroutine to be invoked is deciared wiih: 
the GENERIC attribute (discussed in “Generic entries” on page 118). 


built-in name 
specifies the name of the subroutine to be invoked is declared with the 
BUILTIN attribute, (discussed in “Declaring built-in functions” on 
page 371). 


argument 
Element or an element expression or an aggregate to be passed to the 
invoked subroutine. See “Passing arguments to procedures” on 
page 108. 


References and expressions in the CALL statement are evaluated in the block in 
which the call is executed. This includes execution of any ON-units entered as the 
result of the evaluations. 


RETURN statement 


The RETURN statement terminates execution of the subroutine or function proce- 
dure that contains the RETURN statement and returns control to the invoking pro- 
cedure. Control is returned to the point immediately following the invocation 
reference. 


Return from a subroutine | 
To return from a subroutine, the RETURN statement syntax is: 


>>—RETURN— ; AAA AAA AA ir 


If the RETURN statement terminates the main procedure, the FINISH condition is 
raised prior to program termination. 


Return from a function 
To return from a function, the RETURN statement syntax is: 


p>—RETURN—( express ion) —;- AAA > 


The value returned to the function reference is the value of the expression speci- 
fied, converted to conform to the attributes specified in the RETURNS option of the 
procedure statement. You cannot specify an expression for the RETURN state- 
ment in a BEGIN block. 


OPTIONS option and attribute 


The OPTIONS option can be specified on PACKAGE, PROCEDURE, and BEGIN 
statements. The OPTIONS aittribute can be specified on ENTRY declarations. It is 
used to specify processing characteristics that apply to the block and the invocation 
of a procedure. The options shown in the following syntax diagrams are listed 
alphabetically and discussed starting on page 123. 


Chapter 6. Program organization 121 


OPTIONS option and attribute 


BEGIN statement 
ORDER NOCHARGRAPHIC 

ae Ce ee ee 
REORDER CHARGRAPHIC 


ENTRY declaration 







>>—OPT IONS—( 





PACKAGE statement 


NOCHARGRAPHIC ORDER 
>>—OPTIONS—( = 
CHARGRAPHIC REORDER REENTRANT. 


7 PROCEDURE statement 
> 





>—OPTIONS( 
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OPTIONS option and attribute 


The options are separated by blanks or commas. They can appear in any order. 


ASSEMBLER 


Abbreviation: ASM 
The ASSEMBLER option is a synonym for NODESCRIPTOR. 


BYADDR or BYVALUE 


specify how arguments and parameters are passed and received. 
BYADDR is the default. 


BYVALUE may be specified only for scalar arguments and parameters that 
have known lengths and sizes. 


The BYVALUE and BYADDR attributes can also be specified in the 
description list of an entry declaration and in the attribute list of a param- 
eter declaration. Specifying BYVALUE or BYADDR in an entry or a . 
parameter declaration overrides the option specified in an OPTIONS state- 
ment. 


The following examples show BYVALUE and BYADDR in both entry decla- 
rations and in the OPTIONS statement. The examples assume that the 
compiler option DEFAULT(BYADDR) is in effect. 


Example 1 


dcl D entry (fixed bin byaddr, 
ptr, 
char(4) byvalue) 
options(byvalue); 


Ds sproctl. Be.) 
options (byvalue); 
dcl I fixed bin byaddr, 
Pipers 
C char(4) byvalue; 


call E2(P); 


Example 2 


dc] F entry (fixed bin byaddr, 
ptr, 
char(4) byvalue) 
options(byaddr); 


F: proc(I,P,C) options(byaddr); 


dcl I fixed bin byaddr; 
dcl P ptr byaddr; 
dcl C char(4) byvalue; 


Call EStC)s 


dcl E4 entry(fixed bin byvalue); 


call E4(1); 


CHARGRAPHIC or NOCHARGRAPHIC 


/* 


/* 


/* 


/* 
/* 
/* 


/* 


Abbreviations: CHARG, NOCHARG 


The default for an external procedure is NOCHARG. Internal procedures and 
begin blocks inherit their defaults from the containing procedure. 


byvalue not needed 


P is passed BYADDR 


byaddr not needed 


byaddr not needed 
byaddr not needed 
byvalue needed 


C is passed by address 


I is passed by value 
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OPTIONS option and attribute 


When CHARG is in effect, the following semantic changes occur: 
* All character string assignments are considered to be mixed character 
assignments. 


°* STRINGSIZE condition causes MPSTR built-in function to be used. 
STRINGSIZE must be enabled for character assignment that can cause 
truncation and intelligent DBCS truncation is required. (For information on 
the MPSTR BUILTIN see “MPSTR’” on page 415.) For example: 


Name: procedure options(chargraphic; 
dcl A char(5); 
dcl B char(8); 


/* the following statement... a 
(stringsize): A=B; 
/*...is logically transformed into... */ 


A=mpstr(B, 'vs', length(A)); 


When NOCHARG is in effect, no semantic changes occur. 


COBOL 
has the same effect as NODESCRIPTOR. 


DESCRIPTOR or NODESCRIPTOR 
indicates whether the procedure specified in the entry declaration or procedure 
statement will be passed a descriptor list when it is invoked. 


lf DESCRIPTOR appears, the compiler will pass a descriptor list, if necessary. 
lf NODESCRIPTOR appears, the compiler will not pass a descriptor list. 


If neither appears, DESCRIPTOR is assumed only when one of the invoked 
procedure's parameters is a string, array, area, structure, or union. 


0 ne eS eel nt a oe 9S -1-m e-e ae t 


declaration in which any of the parameters or elements use the asterisk (* ) to 
indicate the extents, length, or size, or if any parameter is NONCONNECTED. 


FORTRAN 
has the same effect as NODESCRIPTOR. 


LINKAGE 
specifies the calling convention to be used for the procedure. 


OPTLINK 
is the default, and provides a faster alternative to the SYSTEM linkage con- 
vention. It is not standard for all OS/2 applications, however. 


SYSTEM 
is the calling convention normally used for calls to the operating system. 
Although it is slower than OPTLINK, it is standard for all OS/2 applications 
and is used for calling OS/2 application programming interfaces. 


For more information about calling conventions, refer to PL/I] Package/2 
Programming Guide. 
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OPTIONS option and attribute 


MAIN 
indicaies thai this external procedure is ihe initial procedure of a PL/! program. 
MAIN is valid, and required, only on one external procedure per program. The 
operating-system control program invokes it as the first step in the execution of 
that program. 


NOEXECOPS 
The NOEXECOPS option is valid only with the MAIN option. It specifies that 
the run-time options will not be specified on the command or statement that 
invokes the program. Only parameters for the main procedure will be specified. 


ORDER or REORDER 
ORDER and REORDER are optimization options that are specified for a proce- 
dure or begin block. 


ORDER indicates that only the most recently assigned values of variables mod- 
ified in the block are available for ON-units that are entered because of compu- 
tational conditions raised during statement execution and expressions in the 
block. 


The REORDER option allows the compiler to generate optimized code to 
produce the result specified by the source program when error-free execution 
takes place. 


For more information on using the ORDER and REORDER options, refer to 
PLA Package/2 Programming Guide. 


If neither option is specified for the external procedure, the default is set by the 
DEFAULT compiler option. Internal blocks inherit ORDER or REORDER from 
the containing block. 


REDUCIBLE or IRREDUCIBLE 
Abbreviations: RED, IRRED 


REDUCIBLE indicates that a procedure or entry need not be invoked multiple 
times if the argument(s) stays unchanged, and that the invocation of the proce- 
dure has no side effects. 


For example, a user-written function that computes a result based on 
unchanging data should be declared REDUCIBLE. A function that computes a 
result based on changing data, such as a random number or time of day, 
should be declared IRREDUCIBLE. 


REENTRANT 
PL/I compiler for OS/2 programs are always reentrant. 


RETCODE 
has no effect. 


Chapter 6. Program organization 125 


RETURNS 


WINPROC 
indicates that this procedure is a window procedure in a Presentation Manager” 
(PM) application. It gets control from PM and returns control to it. If any 
exceptions occur in this procedure or any of its descendants, normal condition 
handling actions will be taken as if this were the main procedure. That is, only 
on-units established in this procedure and any blocks activated by this proce- 
dure will be able to get control. 


The PL/I implicit action following the FINISH condition normally results in termi- 
nating the program, but in this case, the implicit action is to return normally to 
PM with an appropriate return code. 


The WINPROC option must be used to avoid system crashes if a window pro- 
cedure could incur an exception and does have an not an appropriate ON-unit 
to handle it. 


RETURNS option and attribute 


If a procedure is a function procedure, you must specify the RETURNS option on 
the procedure statement. Further, in the invoking procedure or package, you must 
declare such a procedure as an entry with the RETURNS attribute. The RETURNS 
option and the RETURNS attribute are used to specify the attributes of the value 
that is being returned. The attributes in the RETURNS option must match the attri- 
butes in the RETURNS attribute. 


Procedures that are subroutines (and are therefore invoked using the CALL state- 
ment) must not have the RETURNS option on the procedure statement and their 
entry declaration must not have the RETURNS attribute. 


The syntax for RETURNS is: 


>» RETURNS —(—“- attribute) 








The attributes are specified in the same way as they are in a declare statement. 
Defaults are applied in the normal way. 


The attributes that can be specified are any of the data attributes and alignment 
attributes for scalar variables as shown in Figure 10 on page 29. ENTRY vari- 
ables must have the LIMITED attribute. 


String lengths and area sizes must be specified by constants. The returned value 
has the specified length or size. 
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Chapter 7. Data declaration 


When a PL/I program is executed, it can manipulate many different data items. 
Each data item, except a literal arithmetic or string constant, is referred to in the 
program by a name. Each data name is given attributes and a meaning by a dec- 
laration (explicit or implicit). 


Most attributes of data items are known at the time the program is compiled. For 
nonstatic items, attribute values (the bounds of the dimensions of arrays, the 
lengths of strings, area sizes, initial values) and some file attributes can be deter- 
mined during execution of the program. Refer to “Block activation” on page 91 for 
more information. 


Data items, types, and attributes are introduced in Chapter 3, “Data elements” on 
page 24 


This chapter discusses explicit and implicit declarations, scalar, array, structure, 
and union declarations, scope of names, data alignment, and default attributes. 


Explicit declaration 
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A name is explicitly declared if it appears: 


* In a DECLARE statement. The DECLARE statement explicitly declares attri- 
butes of names. 


* As an entry constant. Labels of PROCEDURE statements constitute declara- 
tions of the entry constants within the containing procedure. 


* As a label constant. A label constant explicitly declares a label. 


* As a format constant. A label on a FORMAT statement constitutes an explicit 
declaration of the label. 


The scope of an explicit declaration of a name is the block containing the declara- 
tion. This includes all contained blocks, except those blocks (and any blocks con- 
tained within them) to which another explicit declaration of the same name is 
internal. In the following diagram, the lines indicate the scope of the declaration of 
the names. 


© Copyright IBM Corp. 1992 


DECLARE 





B and B' indicate the two distinct uses of the name B; C and C' indicate the two 
uses of the name C. 


For more information about scope, refer to “Scope of declarations” on page 132. 


DECLARE statement 


The DECLARE statement specifies some or all of the attributes of a name. If the 
attributes are not explicitly declared and cannot be determined by context, default 
attributes are applied. 


DECLARE statements can be an important part of the documentation of a program. 
Consequently, you can make liberal use of declarations, even when default attri- 
butes suffice or when an implicit declaration is possible. Because there are no 
restrictions on the number of DECLARE statements, you can use different 
DECLARE statements for different groups of names. Any number of names can be 
declared in one DECLARE statement. 


eer 
level - attributes 


attributes: 


complementary-attributes 





Abbreviation: DCL 


For more information about declaring arrays, structures, and unions, refer to 
“Arrays” on page 144 or “Structures” on page 147 or “Unions” on page 149. 


m cannot be used as the name of an INTERNAL or an EXTERNAL scalar or 
as the name of a level 1 EXTERNAL structure or union unless the 
EXTERNAL attribute specifies an environment name. 
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Factoring attributes 


attributes 
The attributes can appear in any order. 


All attributes given explicitly for the name must be declared together in a 
DECLARE statement, except that: 


* Names having the FILE attribute can also be given attributes in an 
OPEN statement (or have attributes implied by an implicit opening). 
For more information on the OPEN statement, see “OPEN statement” 
on page 236. 


* The parameter attribute is contextually applied by the appearance of 
the name in a parameter list. A DECLARE statement internal to the 
block can specify additional attributes. 


Attributes of external names, in separate blocks and compilations, must be 
consistent. 


For more information about attributes and the members of the given 
groups, refer to “Data types and attributes” on page 25. 


level A nonzero integer. If a level number is not specified, /eve/ 7 is the default 
for element and array variables. Level 7 must be specified for major struc- 
ture and union names. 


name Each level-1 name must be unique within a block. For more information 
on level-1 names, refer to “Structures” on page 147. 


Condition prefixes and labels cannot be specified on a DECLARE statement. 
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Attributes common to several names can be factored to eliminate repeated specifi- 
cation of the same attributes. Factoring is achieved by enclosing the names in 
parentheses followed by the set of attributes which apply to all of the names. Fac- 
toring can be nested. The dimension attribute can be factored. Factoring can also 
be used on elementary names within structures and unions. A factored level 
number must precede the parenthesized list. 


Names within the parenthesized list are separated by commas. No factored attri- 
bute can be overridden for any of the names, but any name within the list can be 
given other attributes as long as there is no conflict with the factored attributes. 


The following examples show factoring. The last declaration in the set of examples 
shows nested factoring. 


declare (A,B,C,D) binary fixed (31); 
declare (E decimal(6,5), F character(10)) static; 
declare 1 A, 2(B,C,D) (3,2) binary fixed (15); 


declare ((A,B) fixed(10),C float(5)) external; 
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Implicit declaration 


If aname appears in a program and is not explicitly declared, it is implicitly 
declared. The scope of an implicit declaration is determined as if the name were 
declared in a DECLARE statement immediately following the PROCEDURE state- 
ment of the external procedure in which the name is used. 


With the exception of files, entries, and built-in functions, implicit declaration has the 
same effect as if the name were declared in the outermost procedure. For files and 
built-in functions, implicit declaration has the same effect as if the names were 
declared in the logical package outside any procedures. 


Note: Using implicit declarations for anything other than built-in functions and the 
files SYSIN and SYSPRINT is in violation of the 1987 ANSI standard and should be 
avoided. 


Some attributes for a name declared implicitly can be determined from the context 
in which the name appears. These cases, called contextual declarations, are: 


- © Aname of a built-in function. 


* Aname that appears in a CALL statement or the CALL option of INITIAL, or 
that is followed by an argument list, is given the ENTRY and EXTERNAL attri- 
butes. 


* A name that appears in the parameter list of a PROCEDURE statement is 
given the PARAMETER attribute. 


* A name that appears in a FILE or COPY option, or a name that appears in an 
ON, SIGNAL, or REVERT statement for a condition that requires a file name, is 
given the FILE attribute. 


* Aname that appears in an ON CONDITION, SIGNAL CONDITION, or REVERT 
CONDITION statement is given the CONDITION attribute. 


* A name that appears in the BASED attribute, in a SET option, or on the left- 
hand side of a locator qualification symbol is given the POINTER attribute. 


* A name that appears in an IN option, or in the OFFSET attribute, is given the 
AREA attribute. 


Examples of contextual declaration are: 
read file (PREQ) into (Q); 


allocate X in (S); 


In these statements, PREQ is given the FILE attribute, and S is given the AREA attri- 
bute. 


Implicit declarations that are not contextual declarations acquire all attributes by 
default, as described in “Defaults for attributes” on page 141. Because a contex- 
tual declaration cannot exist within the scope of an explicit declaration, it is impos- 
sible for the context of a name to add to the attributes established for that name in 
an explicit declaration. 
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Scope of declarations 
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The part of the program to which a name applies is called the scope of the declara- 
tion of that name. In most cases, the scope of the declaration of a name is deter- 
mined entirely by the position where the name is declared within the program. 
Implicit declarations are treated as if the name were declared in a DECLARE state- 
ment immediately following the PROCEDURE statement of the external procedure. 


It is not necessary for a name to have the same meaning throughout a program. A 
name explicitly declared within a block has a meaning only within that block. 
Outside the block, the name is unknown unless the same name has also been 
declared in the outer block. Each declaration of the name establishes a scope and 
in this case, the name in the outer block refers to a different data item. This 
enables you to specify local definitions and, hence, to write procedures or begin- 
blocks without knowing all the names used in other parts of the program. 


In the following example, the output for A is actually C.A, which is 2. The output for 
B is 1, as declared in procedure X. 
X: proc options(main); 

‘del (A,B) char(1) init('1"); 

Call Xs 

return; 


Tes PROG. 
deh a, 
3 A Charcl) -inite"2"): 
put data(A,B); 
return; 
end Y; 
end X; 


Thus, for nested procedures, PL/I uses the variable declared within the current 
block before using any variables that are declared in containing blocks. 


can al. 


in order to UNGErstand ine scope of ihe Geciaration of a name, you musi under- 
stand the terms contained in and internal to. 


All of the text of a block, from the PACKAGE, PROCEDURE, or BEGIN statement 
through the corresponding END statement (including condition prefixes of BEGIN, 
PACKAGE, and PROCEDURE statements), is said to be contained in that block. 
However, the labels of the BEGIN or PROCEDURE statement heading the block 
are not contained in that block. Nested blocks are contained in the block in which 
they appear. 


Text that is contained in a block, but not contained in any other block nested within 
it, is said to be internal to that block. Entry names of a procedure (and labels of a 
BEGIN statement) are not contained in that block. Consequently, they are internal 
to the containing block. Entry names of an external procedure are treated as if 
they were external to the external procedure. 


PL/I Package/2 Language Reference 


Scope of declarations 


Figure 28 illustrates the scopes of data declarations. 


A_and_D: package exports(*); 
dcl X static, 
Y based; 


A: procedure; 
declare P, Q; 
B: Procedure; 
declare Q; 
=Q; 
begin; 
declare R; 


do I = 1 to 10; 
d; 


procedure; 
declare S; 


end A_and_D; 





Figure 28. Scopes of data declarations 

The brackets to the left indicate the block structure; the brackets to the right show 
the scope of each declaration of a name. The scopes of the two declarations of 0 
and R are shown as Q and Q' and R and R’. 


Note that X and Y are visible to all of the procedures contained in the package. 


Ll P is declared in the block A and known throughout A because it is not rede- 
clared. 
il Q is declared in block A, and redeclared in block 8. The scope of the first 


declaration of Q is all of A except B; the scope of the second declaration of 
Q is block B only. 


| R is declared in block C, but a reference to R is also made in block B. The 
reference to R in block 8 results in an implicit declaration of R in A, the 
external procedure. Therefore, two separate names (R and R' in 
Figure 28) with different scopes exist. The scope of the explicitly declared 
R is block C; the scope of the implicitly declared R in block B is all of A 
except block C. 


a | | is referred to in block C. This results in an implicit declaration in the 
external procedure A. As a result, this declaration applies to all of A, 
including the contained procedures B, C, and D. 


ie | S is explicitly declared in procedure D and is known only within D. 


Figure 29 illustrates the scopes of entry constant and statement label declarations. 
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INTERNAL and EXTERNAL 


A_and_D: package exports(*); 


A: procedure; 
declare E entry; 
Ll: P=Q; 
B: procedure; 
L2: call C; 
C: procedure; 
Ll: X=Y; 
call E: 
end C; 
go to L1; 
one B; 
: procedure; 
L end D; 
call B; 
end A; 


E: procedure; 
Cend Ee 


end A_and_D; 





Figure 29. Scopes of entry and label declarations 


Figure 29 shows two external procedures, A and E. 


EI 
i 


BI 


a 


ie 
il 


The scope of the declaration of the name A is only all of the block A, and 
not E. 


E is explicitly declared in A as an external entry constant. The explicit 
declaration of E applies throughout block A. It is not linked to the explicit 
declaration of E that applies throughout block E. The scope of the declara- 
tion of the name E is all of block A and all of block E. 


The label L1 appears with statements internal to A and to C. Two separate 
deciarations are therefore established; the first applies to all of block A 
except block C, the second applies to block C only. Therefore, when the 
GO TO statement in block B executes, control transfers to L1 in block A, 
and block B terminates. 


D and B are explicitly declared in block A and can be referred to anywhere 
within A; but because they are INTERNAL, they cannot be referred to in 
block E. 


C is explicitly declared in B and can be referred to from within B, but not 
from outside B. 


L2 is declared in B and can be referred to in block 8, including C, which is 
contained in B, but not from outside B. 


INTERNAL and EXTERNAL attributes 
The INTERNAL and EXTERNAL attributes define the scope of a name. 


INTERNAL specifies that the name can be known only in the declaring block. Any 
other explicit declaration of that name refers to a new object with a different scope 
that does not overlap. 


A name with the EXTERNAL attribute can be declared more than once, either in 
different external procedures or within blocks contained in external procedures. All 
declarations of the same name with the EXTERNAL attribute refer to the same 
data. The scope of each deciaration of the name (with the EXTERNAL attribute) 
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INTERNAL and EXTERNAL 


includes the scopes of all the declarations of that name (with EXTERNAL) within 
the appiicaiion. 


The syntax for the INTERNAL and EXTERNAL attributes is: 


>> INTERNAL < 
a 
(—envi ronment -name—) 





Abbreviations: INT for INTERNAL, EXT for EXTERNAL 


environment-name 
specifies the name by which the procedure or variable is known outside of the 
compilation unit. 


When so specified, the name being declared effectively becomes internal and 
is not known outside of the compilation unit. The environment name is known 
instead. 


Note: Use of environment names can limit the portability of your application. 


INTERNAL is the default for entry names of internal procedures and for variables 
with any storage class except controlled. 


EXTERNAL is the default for file constants, entry constants, programmer-defined 
conditions, and controlled variables. 


When a major structure or union name is declared EXTERNAL in more than one 
block, the attributes of the members must be the same in each case, although the 
corresponding member names need not be identical. 


In the following example: 


ProcA: procedure; 
declare 1 A external, 
am 
fa 


end Procd; 
process; 
ProcB: procedure; 
declare 1 A external, 
2 By 
2 Ds 


end ProcB; 


If A.B is changed in ProcA, it is also changed for ProcB, and vice versa; if A.C is 
changed in ProcA, A.D is changed for ProcB, and vice versa. 


Members of structures and unions always have the INTERNAL attribute. 
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Because external declarations for the same name all refer to the same data, they 
must all result in the same set of attributes. When EXTERNAL names are declared 
in different external procedures, the user has the responsibility to ensure that the 
attributes are matching. Figure 30 illustrates a variety of declarations and their 
scopes. 


Scope_Example: package exports(*); 
A: procedure; 
declare S character (20); 
dcl Set entry(fixed decimal(1)), 
Out entry(label); 
call Set (3); 
: get list (S,M,N); 
: begin; 
declare X(M,N), Y(M); 
get list (X,Y); 
Call COXYDs 


C: procedure (P,Q); 
declare 
ear oe 
OC); 
S binary fixed external; 
S=0; 
do I = 1 to™M; 
if sum (P(I,*)) = Q(I) then 
go to B; 
S = Stl; 
if S = 3 then 
call Out (E); 
Cal DCL 
B: end; 
end C; 


D: procedure (N); 
put list (‘Error in row ', 
N, ‘Table Name ', S); 


end D; 
end B; 
go to E; 
end A; 
Out: procedure (R); 
Declare 
R Label, 
(K static internal, 
L static external) init (0), 
S binary fixed external, 
Z fixed decimal(1); 
K = Ktl; S=0; 
if K<L then 
stop; 
else go to R; 


procedure (Z); 
declare Z fixed dec(1); 
L=Z; 
declare L external init(0); 
return; 
end; 

end Scope_Example; 





Figure 30. Example of scopes of various declarations 


hl A is an external procedure name. Its scope is all of block A, plus any other 
blocks where A is declared as external. 
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iS 


Ml 
a 


i] 


Vi 


ie 
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INTERNAL and EXTERNAL 


S is explicitly declared in block A and block C. The character variable dec- 
laration applies to all ot block A except biock C. The fixed binary declara- 
tion applies only within block C. Notice that although D is called from within 
block C, the reference to S in the PUT statement in D is to the character 
variable S, and not to the S declared in block C. 


N appears as a parameter in block D, but is also used outside the block. 
lis appearance as a parameter establishes an explicit declaration of N 
within D. The references outside D cause an implicit declaration of N in 
block A. These two declarations of the name N refer to different objects, 
although in this case, the objects have the same data attributes, which 
are, by default, FIXED BIN(15,0) and INTERNAL. Under DFT(ANS), the 
precision is (31,0). 


X and Y are known throughout B and can be referred to in block C or D 
within B, but not in that part of A outside B. 


P and Q are parameters, and therefore if there were no other declaration of 
these names within the block, their appearance in the parameter list would 
be sufficient to constitute a contextual declaration. However, a separate, 
explicit declaration statement is required in order to specify that P and Q 
are arrays. Although the arguments X and Y are declared as arrays and 
are known in block C, it is still necessary to declare P and Q in a DECLARE 
statement to establish that they, too, are arrays. (The asterisk notation 
indicates that the bounds of the parameters are the same as the bounds 
of the arguments.) 


I and M are not explicitly declared in the external procedure A. Therefore, 
they are implicitly declared and are known throughout A, even though I 
appears only within block C. 


The Out and Set external procedures in the example have an external dec- 
laration of L that is common to both. They also must be declared explicitly 
with the ENTRY attribute in procedure A. Because ENTRY implies 
EXTERNAL, the two entry constants Set and Out are known throughout 
the two external procedures. 


The label B appears twice in the program—first in A, as the label of a 
begin-block, which is an explicit declaration, and then redeclared as a 
label within block C by its appearance as a prefix to an END. statement. 
The go to B statement within block C, therefore, refers to the label of the 
END statement within block C. Outside block C, any reference to B is to 
the label of the begin block. 


Blocks C and D can be called from any point within B but not from that part 
of A outside B, nor from another external procedure. Similarly, because 
label E is known throughout the external procedure A, a transfer to E can 
be made from any point within A. The label B within block C, however, can 
be referred to only from within C. Transfers out of a block by a GO TO 
statement can be made; but such transfers into a nested block generally 
cannot. An exception is shown in the external procedure Out, where the 
label E from block C is passed as an argument to the label parameter R. 


Note that, with no files specified in the GET and PUT statements, SYSIN 
and SYSPRINT are implicitly declared. 


The statement else go to R; transfers control to the label E, even though 
E is declared within A, and not known within Out. 
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fii The variables kK (INTERNAL) and L (EXTERNAL) are declared as STATIC 
within the Out procedure block; their values are preserved between calls to 
Out. 


12] In order to identify the S in the procedure Out as the same S in the proce- 
dure C, both are declared with the attribute EXTERNAL. 


RESERVED attribute 


RESERVED indicates that the compilation unit containing the declared variable is 
linked with at least one other compilation unit that declares the same variable with 
the STATIC and EXTERNAL attributes and without the RESERVED attribute. The 
RESERVED attribute implies STATIC and EXTERNAL attributes, but does not allo- 
cate or initialize storage for the variable. 


The syntax for the RESERVED attribute is: 


>> —RE SERVED ________________>< 


Data alignment 


The computer holds information in multiples of units of 8 bits. Each 8-bit unit of 
information is called a byte. 


The computer accesses bytes singly or as halfwords, words, or doublewords. A 
halfword is 2 consecutive bytes. A fullword is 4 consecutive bytes. A doubleword 
is 8 consecutive bytes. Byte locations in storage are consecutively numbered 
starting with 0; each number is the address of the corresponding byte. Halfwords, 
words, and doublewords are addressed by the address of their leftmost byte. 


Your programs can execute faster if halfwords, words, and doublewords are located 
iii Main storage on an integrai boundary for that unit of information. That is, the 
unit of information's address is a multiple of the number of bytes in the unit, as can 
be seen in Figure 31. 


Figure 31. Alignment on integral boundaries of halfwords, words, and doublewords 
ADDRESSES IN A SECTION OF STORAGE 


halfword halfword halfword 









halfword 











fullword fullword 


doubleword 


PL/I permits data alignment on integral boundaries. However, unused bytes 
between successive data elements can increase storage use. For example, when 
the data items are members of aggregates used to create a data set, the unused 
bytes increase the amount of auxiliary storage required. The ALIGNED and UNA- 
LIGNED attributes allow you to choose whether or not to align data on the appro- 
priate integral boundary. 
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ALIGNED and UNALIGNED attributes 


ALIGNED specifies that the data element is aligned on the storage boundary corre- 
sponding to its data-type requirement. These requirements are shown in 
Figure 32. 


Figure 32 (Page 71 of 2). Alignment requirements 
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Variable Type Stored Internally as: 
ALIGNED: 
One byte for each group of 8 ALIGNED: 
bits (or part thereof) CEIL(n/8) Bit 

(Data may begin on any bit 

UNALIGNED: UNALIGNED: in any byte, (0) through 7) 
As many bits as are required, n bits 

BIT (n) regardless of byte boundaries 






CHARACTER (n) One byte per character a 
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PICTURE character (except V, K, and the 






ters other than V, K, 
and F specification 


Packed decimal format (1/2 
DECIMAL FIXED (p,q) byte per digit, plus 1/2 byte for CEIL((p+1)/2 
sign) 
BINARY FIXED(p,q) 
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UNSIGNED 1 <= p <= 8 
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Re character of the declared Halfword (Data may 
maximum length ’ begin on byte 0, 2, 4, or 
Two-byte prefix plus 2 bytes 
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VARYING per graphic of the declared 


maximum length 


BINARY FIXED(p,q) 
SIGNED 7 <= p <= 15 Halfword 
UNSIGNED 8 <= p <= 16 


BINARY FIXED(p,q) 
SIGNED 15 <p <= 31 Fullword 
UNSIGNED 16 <= p <= 31 
BINARY FLOAT (p) 4 
1<=p<=21 
Short floating-point 
DECIMAL FLOAT (p) 
1<=p<=6 


POINTER 
OFFSET 
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Fullword (Data may begin 
on byte 0 or 4) 









Fullword 
(Data may begin on byte 
0 or 4) 


Byte 
(Data may begin on any 


ENTRY LIMITED byte, 0 through 7) 


ENTRY 
LABEL or FORMAT 
Alignment and storage requirements for program control data can vary across supported systems. 


Complex data requires twice as much storage as its real counterpart, but the alignment requirements are the same. 
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Figure 32 (Page 2 of 2). Alignment requirements 
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AREA 
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BINARY FLOAT (p) 
22<=p<=53 


DECIMAL FLOAT (p) 
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BINARY FLOAT(p) 
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DECIMAL FLOAT(p) 
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Alignment and storage requirements for program control data can vary across supported systems. 


Complex data requires twice as much storage as its real counterpart, but the alignment requirements are the same. 


UNALIGNED specifies that each data element is mapped on the next byte 
boundary, except for fixed-length bit strings, which are mapped on the next bit. 
The syntax for the ALIGNED and UNALIGNED attributes is: 


Sp pe = ee 
UNALIGNED 





Defaults are applied at element level. UNALIGNED is the default for bit data, char- 
acter data, graphic data, and numeric character data. ALIGNED is the default for 
all other types of data. 


ALIGNED or UNALIGNED can be specified for element, array, structure or union 
variables. The application of either attribute to a structure or union is equivalent to 
applying the attribute to all contained elements that are not explicitly declared 
ALIGNED or UNALIGNED. 


The following example illustrates the effect of ALIGNED and UNALIGNED declara- 
tions for a structure and its elements: 


declare 1 S, 

2 X bit(2), /* unaligned by default */ 

2 A aligned, /* aligned explicitly 7 

3B; /* aligned from A xf 

3 C unaligned, /* unaligned explicitly */ 

4D, /* unaligned from C */ 

4 aligned, /* aligned explicitly */ 

4 F, /* unaligned from C * 

3G, /* aligned from A xy 

Ze /* aligned by default * if 


For more information about structures and unions, refer to “Structures” on 
page 147 and “Unions” on page 149. 
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Defaults for attributes 


Every name in a PL/I program requires a complete set of attributes. Arguments 
passed to a procedure must have attributes matching the procedure's parameters. 
Values returned by functions must have the attributes expected. However, the attri- 
butes that you specify need rarely include the complete set of attributes. 


The set of attributes for: 


* Explicitly declared names 

* Implicitly (including contextually) declared names 
* Attributes to be included in parameter descriptors 
* Values returned from function procedures 


can be completed by using the language-specified defaults, or by defaults that you 
can define (using the DEFAULT statement) either to modify the language-specified 
defaults or to develop a completely new set of defaults. 


Attributes applied by default cannot override attributes applied to a name by explicit 
or contextual declaration. 


Language-specified defaults 
When a variable has not been declared with any data attributes, it is given arith- 
metic attributes by default. If mode, scale and base are not specified by a 
DECLARE or DEFAULT statement, the DEFAULT compiler option determines its 
attributes as follows: 


° If DEFAULT(IBM) is in effect, variables with names beginning with the letters | 
through N are given the attributes REAL FIXED BIN(15,0); all other variables 
are given the attributes REAL FLOAT DEC(6). 


* If DEFAULT(ANS) is in effect, all variables are given the attributes REAL 
FIXED BIN(31,0) 


If a scaling factor is specified in the precision attribute, the attribute FIXED is 
applied before any other attributes. Therefore, a declaration with the attributes 
BIN(p,q) is always equivalent to a declaration with the attributes FIXED BIN(p,q). 


If a precision is not specified in an arithmetic declaration, the DEFAULT compiler 
option determines the precision as indicated in Figure 33 on page 142. The 
language-specified defaults for scope, storage and alignment attributes are shown 
in Figure 10 on page 29 and Figure 9 on page 28. 


If no description list is given in an ENTRY declaration, the attributes for the argu- 
ment must match those specified for the corresponding parameter in the invoked 
procedure. For example, given the following declaration: 


dcl x entry; 
call x( 1 ); 


The argument has the attributes REAL FIXED DEC(1,0). This would be an error if 
the procedure x declared its parameter with other attributes, as shown in the fol- 
lowing example: 


X: proc( y ); 
dcl y fixed bin(15); 
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DEFAULT 


This potential problem can be easily avoided if the entry declaration specifies the 
attributes for all of its parameters. 


Figure 33. Default arithmetic precisions 


Attributes DEFAULT(IBM) |§ DEFAULT(ANS) 
DECIMAL FIXED (5,0) (10,0) 

BINARY FIXED (15,0) (31,0) 

DECIMAL FLOAT (6) (6) 

BINARY FLOAT (21) (21) 


DEFAULT statement 


The DEFAULT statement specifies data-attribute defaults (when attribute sets are 
not complete). Any attributes not applied by the DEFAULT statement for any 
partially-complete explicit or contextual declarations, and for implicit declarations, 
are supplied by language-specified defaults. 


The DEFAULT statement overrides all other attribute specifications. 
Structure and union elements are given default attributes according to the name of 
the element, not the qualified element name. The DEFAULT statement cannot be 


used to create a structure or a union. 


The syntax for the DEFAULT statement is: 


>>—DEFAULT—RANGE—( + identifier )————————__—_—_> 
| identifier 
*. 


»—attribute-speci fication—;————_—_____________________________» « 





Abbreviation: DFT 


RANGE(identifier) 
specifies that the defaults apply to names that begin with or exactly match 
the identifier specified. Identifier can be a complete or partial identifier. 
For example: 


range (ABC) 


applies to these names: 


ABC 
abcd 
ABCDE 


but not to: 


ABD 
acb 
AB 
A 


Hence, a single character in the range-specification applies to all names 
that start with that character. 
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RANGE (identifier:identifier) 
speciiies inai ine defaulis apply io names that begin with or exactly match 
the identifiers in the range specified. Identifier can be a complete or 
partial identifier but should not have any DBCS characters. The second 
identifier in the range must be greater than or equal to the first identifier. 
For example: 


range(A:C, Fred : Harry) 


applies to these names: 


ABC 

BCA 

G 

FRED 
George 
Harrison 


but not to: 


DBA 
FLAG 
HarrysWorld 


RANGE(*) 
specifies all names (including * names) in the scope of the DEFAULT 
statement. For example: 


dft range (*) fixed bin; 


This statement specifies default attributes FIXED BIN, with default preci- 
sion for all names. 


attribute-specification 
specifies a list of attributes from which selected attributes are applied to 
names in the specified range. (Attributes are listed in “Data types and 
attributes” on page 25.) Attributes in the list can appear in any order and 
must be separated by blanks. 


Only those attributes that are necessary to complete the Geclaration ofa 
data item are taken from the list of attributes. 


Attributes that conflict, wnen applied to a data item, do not necessarily 
conflict when they appear in an attribute specification. Consider the fol- 
lowing statement: 


default range(S) binary varying; 


Given the declaration dcl sl real, s1 would get the BINARY attribute, but 
with the declaration dcl s2 bit, s2 would get the VARYING attribute. 


There can be more than one DEFAULT statement within a block. The scope of a 
DEFAULT statement is the block in which it occurs, and all blocks within that block 
which neither include another DEFAULT statement with the same range, nor are 
contained in a block having a DEFAULT statement with the same range. 


A DEFAULT statement in an internal block affects only explicitly declared names. 
This is because the scope of an implicit declaration is determined as if the names 
were declared in a DECLARE statement immediately following the PROCEDURE 
statement of the external procedure in which the name appears. 


Chapter 7. Data declaration 143 


Restoring defaults 


It is possible for a containing block to have a DEFAULT statement with a range that 
is partly covered by the range of a DEFAULT statement in a contained block. In 
such a case, the range of the DEFAULT statement in the containing block is 
reduced by the range of the DEFAULT statement in the contained block. For 
example: 


P: procedure; 


default range (XY) fixed; /* First */ 
Q: begin; 

default range (XYZ) float; /* Second */ 

end P; 


The scope of the first DEFAULT statement is procedure P and the contained block 
Q. The range of the first DEFAULT statement is all names in procedure P beginning 
with the characters XY, together with all names in begin block Q beginning with the 
characters XY, except for those beginning with the characters XYZ. 


Restoring language-specified defaults 


Arrays 


The following statement: 
dft range(*) system; 


overrides, for all names, any programmer-defined default rules established in a con- 
taining block. It can be used to restore language-specified defaults for contained 
blocks. 


An array is an n-dimensional collection of elements that have identical attributes. 
Only the array itself is given a name. An individual item of an array is referred to 
by giving its position within the array. You indicate that a name is an array variable 
by providing the dimension attribute. 


DIMENSION attribute 


The dimension attribute specities the number of dimensions of an array and upper 
and lower bounds of each. 


Bounds that are nonrestricted expressions are evaluated and converted to FIXED 
BINARY(M,0) when storage is allocated for the array. 


The extent is the number of integers between, and including, the lower and upper 
bounds. 
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Examples of arrays 


The syntax for the dimension attribute is: 











i bound Ee 


DIMENSION 


bound: 
upper -bound 
lower-bound -: s 
ke 
lower-bound: 


1 
eee eens 
REFER( var7able) 


upper-bound: 


t—expressi a 
REFER( variable) 


Abbreviation: DIM 


If the DIMENSION keyword is omitted, the dimension must immediately follow the 
name (or the parenthesized list of names) in the declaration. 


The number of bounds specifications indicates the number of dimensions in the 
array, unless the declared variable is in an array of structures or unions. In this 
case it inherits dimensions from the containing structure or union. 


The bounds specification indicates the bounds as follows: 
* If only the upper bound is given, the lower bound defaults to 1. 


* The lower bound must be less than or equal to the upper bound. 


* An asterisk (*) specifies that the lower and/or the upper bound is to be taken 
from the argument associated with the parameter. 


Examples of arrays 
Consider the following declaration: 
declare List fixed decimal(3) dimension(8); 
List is declared as a one-dimensional array of eight elements, each one a fixed- 


point decimal element of three digits. The one dimension of List has bounds of 1 
and 8, and its extent is 8. 


In the example: 
declare Table (4,2) fixed dec (3); 


Table is declared as a two-dimensional array of eight fixed-point decimal elements. 
The two dimensions of Table have bounds of 1 and 4 and 1 and 2, and the extents 
are 4 and 2. 


Other examples are: 


declare List_A dimension(4:11); 
declare List_B (-4:3); 
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Subscripts 


In the first example, the bounds are 4 and 11; in the second they are -4 and 3. 
The extents are the same for each, 8 integers from the lower bound through the 
upper bound. 


In the manipulation of array data (discussed in “Array expressions” on page 66) 
involving more than one array, the bounds—not merely the extents—must be iden- 
tical. Although List, List_A, and List_B all have the same extent, the bounds are 
not identical. 


Subscripts 


The bounds of an array determine the way elements of the array can be referred 
to. For example, when the following data items: 


20 5 10 30 630 150 310 70 


are assigned to the array List, as declared above, the different elements are 
referred to as follows: 


Reference Element 


LIST (1) 20 
LIST (2) 5 
LIST (3) 10 
LIST (4) 30 
LIST (5) 630 
LIST (6) 150 
LIST (7) 310 
LIST (8) 70 


Each of the parenthesized numbers following LIST is a subscript. A parenthesized 
subscript following an array name reference identifies a particular data item within 
the array. A reference to a subscripted name, such as LIST(4), refers to a single 
element and is an element variable. The entire array can be referred to by the 
unsubscripted name of the array—for example, LIST. 

ta can be assigned io List_A and List_B deciared previousiy. In this 
case it is referenced as follows: 


3 


Reference Element Reference 
LIST_A (4) 20 LIST_B (-4) 
LIST_A (5) 5 LIST_B (-3) 
LIST_A (6) 10 LIST_B (-2) 
LIST_A (7) 30 LIST_B (-1) 
LIST_A (8) 630 LIST_B (0) 
LIST_A (9) 150 LIST_B (1) 
LIST_A (10) 310 LIST_B (2) 
LIST_A (11) 70 LIST_B (3) 


Assume that the same data is assigned to TABLE, which is declared as a two- 
- dimensional array. TABLE can be illustrated as a matrix of four rows and two 
columns: 


TABLE(m,n) = (m,1)_~—s (m,2) 


(1,n) 20 5 
(2,n) 10 30 
(3,n) 630 150 
(4,n) 310 70 
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An element of TABLE is referred to by a subscripted name with two parenthesized 
subscripts, separated by a comma. For exampie, TABLE (2,1) would specify the 
first item in the second row, the data item 10. 


The use of a matrix to illustrate TABLE is purely conceptual. It has no relationship 
to the way the items are actually organized in storage. Data items are assigned to 
an array in row major order. This means that the subscript that represents rows 
varies most rapidly. For example, assignment to TABLE would be to TABLE(1,1), 
TABLE(1,2), TABLE(2,1), TABLE(2,2), and so forth. 


A subscripted reference to an array must contain as many subscripts as there are 
dimensions in the array. 


Any expression that yields a valid arithmetic value can be used for a subscript. If 
necessary, the value is converted to FIXED BINARY(31,0). Thus, TABLE(I,J*K) 
can be used to refer to the different elements of TABLE by varying the values of I, 
J, and K. 


Cross sections of arrays 


Structures 


Cross sections of arrays can be referred to by using an asterisk for a subscript. 
The asterisk specifies that the entire extent is used. For example, TABLE(*,1) 
refers to all of the elements in the first column of TABLE. It specifies the cross 
section consisting of TABLE(1,1), TABLE(2,1), TABLE(3,1), and TABLE(4,1). The 
subscripted name TABLE(2,*) refers to all of the data items in the second row of 
TABLE. TABLE(*,*) refers to the entire array, as does TABLE. 


A subscripted name containing asterisk subscripts represents not a single data 
element, but an array with as many dimensions as there are asterisks. Conse- 
quently, such a name is not an element expression, but an array expression. 


A reference to a cross section of an array can refer to two or more elements that 
are not adjacent in storage. The storage represented by such a cross section is 
known as nonconnected storage. (See “CONNECTED and NONCONNECTED 
attributes” on page 217.) The rule is as follows: if a nonasterisk bound appears to 
the right of the leftmost asterisk bound, the array cross section is in nonconnected 
storage. Thus A(4,*,*) is in connected storage; A(*,2,*) is not. 


A structure is a collection of member elements that may be structures, unions, ele- 
mentary variables and arrays. 


The structure variable is a name that can be used to refer to the entire aggregate 
of data. Unlike an array, however, each member of a structure also has a name, 
and the attributes of each member may differ. An asterisk may be used as the 
name of a structure or a member when it will not be referred to. For example, 
reserved or filler items may be named asterisk. 


A structure has different levels. The name at level-1 is called a major structure. 
Names at deeper levels may be minor structures or unions. Names at the deepest 
level are called elementary names, which can represent an elementary variable or 
an array variable. Unions are described in “Unions” on page 149. 
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Structures 


A structure is described in a DECLARE statement through the use of level numbers 
preceding the associated names. Level numbers must be integers. 


A major structure name is declared with the level number 1. Minor structures, 
unions, and elementary names are deciared with level numbers greater than 1. A 
delimiter (usually a blank) must separate the level number and its associated name. 
For example, the items of a payroll record could be declared as follows: 


declare 1 Payroll, /* major structure name */ 
2 Name, /* minor structure name */ 
3 Last char(20), /* elementary name sa 
3 First char(15), 
2 Hours, 


3 Regular fixed dec(5,2), 

3 Overtime fixed dec(5,2), 
2 Rate, 

3 Regular fixed dec(3,2), 

3 Overtime fixed dec(3,2); 


In the example, Payroll] is the major structure and all other names are members of 
this structure. Name, Hours, and Rate are minor structures, and all other members 
are elementary variables. You can refer to the entire structure by the name 
Payroll, or to portions of the structure by the minor structure names. You can refer 
to a member by referring to the member name. 


Indentation is only for readability. The statement could be written in a continuous 
string as: 


Declare 1 Payroll, 2 Name, 3 Last char(20), . 


The level numbers you choose for successively deeper levels need not be consec- 
utive. A minor structure at level n contains all the names with level numbers 
greater than n that lie between that minor structure name and the next name with a 
level number less than or equal to n. 


The description of a maior structure is usually terminated by a semicoion terimi- 
nating the DECLARE statement. It can also be terminated by comma, followed by 
the declaration of another item. 


For example, the following declaration results in exactly the same structure as the 
declaration in the previous example. 


Declare 1 Payroll, 

4 Name, 
5 Last char(20), 
5 First char(15), 

3 Hours, 
6 Regular fixed dec(5,2), 
5 Overtime fixed dec(5,2), 

2 Rate, 
9 Regular fixed dec(3,2), 
9 Overtime fixed dec(3,2); 
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Unions 


A union is a collection of member elements that overlay each other, occupying the 
same storage. The members may be structures, unions, elementary variables, and 
arrays. They need not have identical attributes. 


The entire union is given a name that can be used to refer to the entire aggregate 
of data. Like a structure, each element of a union also has a name. An asterisk 
may be used as the name of a union or a member, when it will not be referred to. 
For example, reserved or filler items may be named asterisk. 


Like a structure, a union may be at any level including level 1. All elements of a 
union at the next deeper level are members of the union and occupy the same 
storage. The storage occupied by the union is equal to the storage required by the 
largest member. Normally, only one member is presumed to be active and valid at 
any time. The determination of which member is active is entirely under pro- 
grammer control. 


A union, like a structure, is declared through the use of level numbers preceding 
the associated names. 


Unions may be used to declare variant records that would typically contain a 
common part, a selector part, and variant parts. For example, records in an client 
file may be declared as follows: 


Declare 1 Client, 
2 Number pic ‘999999’, 
2 Type bit(1), /* Client is an individual */ 
2 PVE) S /* reserved * | 
2 Name union, 
3 Individual, 
5 Last_Name union, 
7 Last char(20), 
7 Initial char(1), 
5 First_Name char(15), 
3 Company char(35), 
2 * char(0); 


In this example, Client is a major structure. The structure Individual, and the 
element Company are members of the union Name. One of these members is active 
depending on Type. The structure Individual contains the union First_name and 
the element Last_name. First_name union has First and Initial as its members, 
both of which are active. The example also shows the use of asterisk as a name. 
The description of a union is terminated by the semicolon that terminates a 
DECLARE statement or by a comma, followed by the declaration of another item. 


UNION attribute 


The UNION attribute allows you to specify that a variable is a union and that its 
members are those that follow it and are at the next logically higher level. 


The syntax is: 


>>—UN 1 ONAA A > 
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Structure/union qualification 


A member of a structure or a union can be referred to its name alone if it is unique. 
If another member has the same name, whether at the same or different level, 
ambiguity occurs. Where ambiguity occurs, a qualified reference is required to 
uniquely identify the correct member. 


A qualified reference is a member name that is qualified with one or more names of 
parent members connected by periods. (See the qualified reference syntax in 
Chapter 4, “Expressions and references” on page 50.) Blanks may appear sur- 
rounding the period. 


The qualification must follow the order of levels. That is, the name at the highest 
level must appear first, with the name at the deepest level appearing last. 


While the level 1 structure or union name must be unique within the block scope, 
member names need not be unique as long as they do not appear at same logical 
level within their most immediate parent. Qualifying names must be used only so 
far as necessary to make the reference unique within the block in which it appears. 
In the following example, the value of x.y (19) is displayed, not the value (17). 


dcl 7 fixed init(17); 


begin; 
dc] 
se 
2 y fixed init(19); 
display( y ); 
end; 


A reference is always taken to apply to the declared name in the innermost block 
containing the reference. 


The following examples illustrate both ambiguous and unambiguous references. In 
the following example, A.C refers to C in the inner block; D.E refers to F in the outer 


block. 
declare 1 A, 2 C, 20D, 3 E; 
begin; 
declare 1A, 2B, 3 C, 3 E; 
A.C = D.E; 


In the following example, D has been declared twice. A reference to A.D refers to 
the second D, because A.D is a complete qualification of only the second D. The 
first D is referred to as A.C.D. 


declare 1 A, 
2 
2 


In the following example, a reference to A.C is ambiguous because neither C can be 
completely qualified by this reference. 
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LIKE attribute 


LIKE 


declare 1 A, 


In the following example, a reference to A refers to the first A, A.A to the second A, 
and A.A.A to the third A. 
declare 1 A, 
2A, 
3 A; 
In the following example, a reference to X refers to the first DECLARE statement. 


A reference to Y.Z is ambiguous. Y.Y.Z refers to the second Z, and Y.X.Z refers to 
the first Z. 


declare X; 
declare 1 Y, 
2X, 
32; 
Shs 
a 
a ee 
SAS 


For more information about name qualification, refer to “Scope of declarations” on 
page 132. 


The LIKE attribute specifies that the name being declared has an organization that 
is logically the same as the referenced structure or union (object of the LIKE attri- 
bute). The object variable's member names and their attributes, including the 
dimension attribute, are effectively copied and become members of the name being 
declared. If necessary, the level numbers of the copied members are automatically 
adjusted. The object variable name and its attributes, including the dimension attri- 
bute, are ignored. 


The syntax for the LIKE attribute is: 


>>—LIKE—object-variab] e—— $$ ——————/ 7 


object-variable 
can be a major structure, a minor structure, or a union. It must be known 
in the block containing the LIKE attribute specification. It can be qualified 
but must not be subscripted. The object or any of its members must not 
have the LIKE attribute or the REFER option. 


The objects in all LIKE attributes are associated with declared names 
before any LIKE attributes are expanded. 


New members cannot be added to the created structure or union. Any level 
number that immediately follows the object variable in the LIKE attribute must be 
equal to or less than the level number of the name with the LIKE attribute. 
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The following declarations yield the same structure for X. 


dc] 
1 A(10) aligned static, 
2B bit(4), 
ae bit(4), 
1 X like A; 


dc| 
1 X, 

2 Be DVECA); 

ZC breca ys 


Notice that the dimension (DIM(10)), ALIGNED, and STATIC attributes are not 
copied as part of the LIKE expansion. 


The LIKE attribute is expanded before the defaults are applied and before the 
ALIGNED and UNALIGNED attributes are applied to the contained elements of the 
LIKE object variable. 


Examples 


Declare 1 A, 
£/ Gy 

So ECS) wun on: 

bo Eds 

Bi EZ, 

F: 

) 


’ 


3 
(10) union, 

Ge23"G> Sch, 
D 


Declare 1B 
7 
2D; 
BEGIN; 

Declare 1 C LIKE B; 
Declare 1 


OC 
oom 
Ro 
~~ 


5 BB LIKE A.C: 
END; 


Deciarations C and D nave the resuits shown in the following example. 


dc] 
LC, /* DIM and UNION not copied. */ 
22. -3° Ge OH; 
2 OD; 
del 1 D(2), 
5 BBs 
6 E(3) union, /* DIM(3) and UNION copied. me 
Peel: /* Note adjusted level numbers. */ 
LEZ: 
b- Fs 


The following example is invalid because C.E has the LIKE attribute. 
declare 1 A like C, 
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The following example is invalid because the LIKE attribute of A specifies a sub- 
structure, G.C, of a structure, G, declared with the LIKE aiiribuie. 


declare 1 A like G.C, 


The following example is invalid because the LIKE attribute of A specifies a struc- 
ture, C, within a structure, B, that contains a substructure, F, having the LIKE attri- 


bute. 
declare 1 A like C, 
1B; 
2 Uy 
3 D, 
ones 
2 F like X 
1 X, 
ae 
ae 


Combinations of arrays, structures, and unions 


Specifying the dimension attribute on a structure or union results in an array of 
structures or an array of unions respectively. The elements of such an array are 
structures or unions having identical names, levels, and members. For example, if 
a structure were used to hold meteorological data for each month of the years for 
the twentieth and the twenty-first centuries, it might be declared as follows: 


Declare 1 Year(1901:2100), 
3 Month(12), 
5 Temperature, 
7 High decimal fixed(4,1), 
7 Low decimal fixed(4,1), 
5 Wind_velocity, 
7 High decimal fixed(3), 
7 Low decimal fixed(3), 
5 Precipitation, 
7 Total decimal fixed(3,1), 
7 Average decimal fixed(3,1), 
3 * char(Q); 


You could refer to the weather data for July 1991 by specifying Year(1991,7). 
Portions of this data could be referred to by Temperature(1991,7) and 
Wind_Velocity(1991,7). Precipitation. Total(1991,7) or Total(1991,7) would both 
refer to the total precipitation during July 1991. 


Temperature.High(1991,3), which would refer to the high temperature in March 
1991, is a subscripted qualified reference. 
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Cross sections of arrays of structures or unions 


The need for subscripted qualified references becomes apparent when an array of 
structures or unions contains members that are arrays. In the following example, 
both A and B are structures. 
declare 1 A (2,2), 
te (BGs 
oi Oe 
3D, 
2 E) fixed bin; 


To refer to a data item, it may be necessary to use as many as three names and 
three subscripts. For example: 


A(1,1).B refers to B, an array of structures. 
A(1,1) refers to a structure. 
A(1,1).B(1) refers to a structure. 
A(1,1).B(2).C refers to an element. 


As long as the order of subscripts remains unchanged, subscripts in such refer- 
ences can be moved to names at a lower or higher level. In the previous example, 
A.B.C(1,1,2) and A(1,1,2).B.C have the same meaning as A(1,1).B(2).C for the 
above array of structures. Unless all of the subscripts are moved to the lowest 
level, the reference is said to have interleaved subscripts, so A.B(1,1,2).C has 
interleaved subscripts. 


Any item declared within an array of structures or unions inherits dimensions 
declared in the parent. In the previous declaration for the array of structures A, the 
array B is a three-dimensional structure, because it inherits the two dimensions 
declared for A. If B is unique and requires no qualification, any reference to a par- 
ticular B would require three subscripts, two to identify the specific A and one to 
identify the specific B within that A. 


Cross sections of arrays of structures or unions 


A reference to a cross section of an array of structures or unions is not allowed. 
That is, tne asterisk notation cannoi be used in a reference uniess aii of the sub- 
scripts are asterisks. 


Structure and union operations 


Structures can be referenced in most contexts that any elementary variable can be 
referenced. For example, you can have structure references in assignments, |/O 
statements, and so on. References to unions or structures that contain unions, 
however, are limited to the following: 


°* Parameters and arguments 


® Storage control and those built-in functions and subroutines that permit struc- 
tures. 


Structure and union mapping 


Individual members of a union are mapped the same way as members of the struc- 
ture. That is, each of the members, if not a union, is mapped as if it were a 
member of a structure. This means that the first storage location for each of the 
members of a union will not overlay each other if each of the members requires 
different alignment and therefore different padding before the beginning of the 
member. 
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Structure and union mapping 


Consider the following union: 


dcl 
1 A union, 
2 


char(1), 
fixed bin(31), 
2 


’ 


B 
3 
3 
E 
3Pchare2),; 

3 G fixed bin(31); 

Three bytes of padding are added between A and B. Two bytes are added between 
A and E. 


In order to ensure that the first storage location of each of the members of a union 
is the same, make sure that the first member of each has the same alignment 
requirement and it is the same as the highest alignment of any of its members (or 
its member's members). 


The remainder of the discussion applies to members of a structure or union, which 
may be minor structures or elementary variables. 


For any major or minor structure, the length, alignment requirement, and position 
relative to an 8-byte boundary depend on the lengths, alignment requirements, and 
relative positions of its members. The process of determining these requirements 
for each level and for the complete structure is known as structure mapping. 


You can use structure mapping for determining the record length required for a 
structure when record-oriented input/output is used, and determining the amount of 
padding or rearrangement required for correct alignment of a structure for locate- 
mode input/output. 


The structure mapping process minimizes the amount of unused storage (padding) 
between members of the structure. It completes the entire process before the 
structure is allocated, according (in effect) to the rules discussed in the following 
paragraphs. 


Structure mapping is not a physical process. Terms such as shifted and offset are 
used purely for ease of discussion, and do not imply actual movement in storage. 
When the structure is allocated, the relative locations are already known as a result 
of the mapping process. 


The mapping for a complete structure reduces to successively combining pairs of 
items (elements, or minor structures whose individual mappings have already been 
determined). Once a pair has been combined, it becomes a unit to be paired with 
another unit, and so on until the complete structure is mapped. The rules for the 
process are categorized as: 


* Rules for determining the order of pairing 
* Rules for mapping one pair. 


These rules are described below, and an example shows an application of the rules 
in detail. It is necessary to understand the difference between the /ogical level and 
the level number of structure elements. The logical levels are immediately 
apparent if the structure declaration is written with consistent level numbers or suit- 
able indentation (as in the detailed example given after the rules). In any case, you 
can determine the logical level of each item in the structure by applying the fol- 


Chapter 7. Data declaration 155 


Rules for order of pairing 
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lowing rule to each item in turn, starting at the beginning of the structure declara- 
tion: 


Note: The logical level of a given item is always one unit deeper than that of its 
immediate containing structure. 


In the following example, the lower line shows the logical level for each item in the 
declaration. 


de). BAY A By. 5075 D5 93 Bee 8. Py fag 


1 2 3 3 Z 3 5 


Rules for order of pairing 
The steps in determining the order of pairing are as follows: 


1. Find the minor structure at the deepest logical level (which we will call logical 
level n). 


2. If more than one minor structure has the logical level n, take the first one that 
appears in the declaration. 


3. Pair the first two elements appearing in this minor structure, thus forming a unit. 
Use the rules for mapping one pair. (See “Rules for mapping one pair.”) 


4. Pair this unit with the next element (if any) declared in the minor structure, thus 
forming a larger unit. 


5. Repeat step 4 until all the elements in the minor structure have been combined 
into one unit. This completes the mapping for this minor structure; its alignment 
requirement and length, including any padding, are now determined and will not 
change (unless you change the structure declaration). Its offset from a 
doubleword boundary is also now determined; note that this offset will be signif- 
icant during mapping of any containing structure, and it may change as a result 
of such mapping. 


6. Repeat steps 3 through 5 for the next minor structure (if any) appearing at 
logical level n in the declaration. 


7. Repeat step 6 until all minor structures at logical level n have been mapped. 
Each of these minor structures can now be thought of as an element for struc- 
ture mapping purposes. 


8. Repeat the pairing process for minor structures at the next higher logical level; 
that is, make n equal to (n-1) and repeat steps 2 through 7. 


9. Repeat step 8 until n = 1; then repeat steps 3 through 5 for the major structure. 


Rules for mapping one pair 

For purposes of this explanation, think of storage as contiguous doublewords, each 
having 8 bytes, numbered 0 through 7, which indicate the offset from a doubleword 
boundary. Think of the bytes as numbered continuously from 0 onwards, starting at 
any byte, so that lengths and offsets from the start of the structure can be calcu- 
lated. 


1. Begin the first element of the pair on a doubleword boundary; or, if the element 
is a minor structure that has already been mapped, offset it from the 
doubleword boundary by the amount indicated. 


2. Begin the second element of the pair at the first valid position following the end 
of the first element. This position will depend on the alignment requirement of 
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the second element. (If the second element is a minor structure, its alignment 
requirement will have been determined aiready.) 


3. Shift the first element towards the second element as far as the alignment 
requirement of the first allows. The amount of shift determines the offset of this 
pair from a doubleword boundary. 


After this process has been completed, any padding between the two elements has 
been minimized and will not change throughout the rest of the operation. The pair 
is now a unit of fixed length and alignment requirement; its length is the sum of the 
two lengths plus padding, and its alignment requirement is the higher of the two 
alignment requirements (if they differ). 


Effect of UNALIGNED attribute 

The example of structure mapping given below shows the rules applied to a struc- 
ture declared ALIGNED. Mapping of aligned structures is more complex because 
of the number of alignment requirements. The effect of the UNALIGNED attribute 
is to reduce to 1 byte the alignment requirements for halfwords, fullwords, and 
doublewords, and to reduce to 1 bit the alignment requirement for bit strings. The 
same structure mapping rules apply, but the reduced alignment requirements are 
used. The only unused storage will be bit padding within a byte when the structure 
contains bit strings. 


AREA data cannot be unaligned. 


lf a structure has the UNALIGNED attribute and it contains an element that cannot 
be unaligned, UNALIGNED is ignored for that element; the element is aligned and 
an error message is put out. For example, in a program with the following declara- 
tion, C is given the attribute ALIGNED because the inherited attribute UNALIGNED 
conflicts with AREA. 
DECLARE 1 A UNALIGNED, 

2B; 

2 C AREA(100); 


Example of structure mapping 


The following example shows the application of the structure mapping rules for a 
structure with the specified declaration. 
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declare 1 A 


2 
Z 


aligned, 
B fixed bin(31), 


> 


float decimal(14), 


WWM 


G, 
5 H character(2), 

5 I float decimal(13), 
J fixed binary(31,0), 
character(2), 

fixed binary(20,0), 


fixed binary(15), 
character(5), 
float decimal(2), 


Dov 


U bit(3), 
V char(1), 
fixed bin(31), 


N 

4 

4 

4 

S 

4 T float decimal(15), 
4 

4 

W 

picture '$9V99'; 


The minor structure at the deepest logical level is G, so this is mapped first. Then —£ 
is mapped, followed by N, S, C, and M, in that order. 


For each minor structure, a table in Figure 34 shows the steps in the process, and 
a diagram in Figure 35 shows a visual interpretation of the process. Finally, the 
major structure A is mapped as shown in Figure 36. At the end of the example, the 
structure map for A is set out in the form of a table (Figure 37) showing the offset 
of each member from the start of A. 
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Offset from 
Doubleword 


Length |Begin [Begin] End | | End | 












Name of 
Element 


Alignment 
Requirement 

































Step 1 Byte 9 1 
Doubleword 8 7 
Step 2 Byte 2 d 
Boubleword 8 
Minor 
Structure 
Step 1 Fullword 
Doubleword : j 
Step 2 Ful lword 4 3 
Doubleword 6 7 
Step 3 Doubleword 4 7 
Ful lword 0 3 
Minor 
Step 1 Hal fword 
Byte 
Step 2 Halfword 
Fullword 
Minor 
nea Pepe peppy 
Step 1 Doubleword 8 
Byte 1 ; 5 0 
Step 2 BOUBIeMers : : 
Minor 
nea oer epee 
Step 1 Doub] eword 
Doubleword 5 ; ‘ 4 i 
Step 2 Doubleword 36 0 3 
Byte 2 4 5 0 36 
Step 3 2 0 5 
0 3 
Minor 
nea a 
Step 1 Fullword 
Doub] eword 5 : 
Step 2 Ful lword 12 4 7 0 
Doub] eword 10 0 1 0 12 
Step 3 Doub! eword a 4 : 
Fullword 4 
Minor 
ec 


*First item shifted right 





Figure 34. Mapping of example structure 
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Mapping of minor structure G 





Figure 35 (Part 1 of 2). Mapping of minor structures 
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Mapping of minor structure S 





Figure 35 (Part 2 of 2). Mapping of minor structures 
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Offset from 
Doub] eword 


























Offset 
from A 


Name of Alignment 


Required 


Length of 
Padding 









Length | Begin 
0 


Fuliword 
Doubleword 


W 





Fullword 
Doubleword 







Doub] eword 
Doub] eword 







0 48 














™S 


Doubleword 
Byte 4 3 


X 


* First item shifted right 





0 76 
a ae 


C (length 44) 





C (length 44) M (length 28) 





C (length 44) M (length 28) 


eS ee 
step 4 |2|1)2/3/4}5[6)7/0}1) |3)4}5[6)7/0}2] [3]4}5]6]7/9}}2)3/4)5}6|7/6 
| | | , | | | | | 
eee ae caer Oa | 





(length 80) 


Figure 36. Mapping of major structure A 
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W 





Figure 37. Offsets in final mapping of structure A 
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Chapier 8. Statemenis 


This chapter lists all of the PL/I and macro facility statements. Statements that are 
described in other chapters are listed with cross-references to the full descriptions. 


%ACTIVATE statement 


The %ACTIVATE macro facility statement is described in ““%ACTIVATE” ‘on 
page 453. 


ALLOCATE statement 


The ALLOCATE statement is described in Chapter 9, “Storage control” on 
page 198. 


Assignment statement 


The assignment statement evaluates an expression and assigns its value to one or 
more target variables. 


This statement is used for internal data movement, as well as for specifying compu- 
tations. (The GET and PUT statements with the STRING option can also be used 
for internal data movement. Additionally, the PUT statement can specify computa- 
tions to be done. See Chapter 12, “Stream-oriented data transmission.”) 


Because the attributes of the target variable or pseudovariable can differ from the 
attributes of the source (a variable, a constant, or the result of an expression), the 
assignment statement might require conversions (see Chapter 5, “Data 
conversion’). 


The syntax for the assignment statement is: 


>> V reference = —expressio 


»BY NAME 





Area assignment is described in “Area data and attribute” on page 211. 


The remaining text discusses: 


°* The requirements for target variables 

* How element and aggregate assignments are performed 
°* How BY NAME assignments are performed 

* How multiple assignment are performed. 


Examples of assignments begin on page 170. 
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Target variables 


The target variables can be element, array, or structure variables; or 
pseudovariables. 


Array targets 

For array assignments, each target variable must be an array of scalars or struc- 
tures. The source must be a scalar or an expression with the same number of 
dimensions and the same bounds for all dimensions as for the target. 


Union targets 
Union assignments are not permitted. 


Structure targets 
For structure assignments, each target variable must be a structure. The right- 
hand side can be a structure reference or element expression. 


If the target in an assignment statement without the BYNAME option is a structure, 
the source must be either a scalar or a structure with the same structuring as the 
target structure. That is, the source must have the same number of members. 
Members that are structures must have the same number of members and the 
same dimensions. 


How assignments are performed 


Element assignments 
Element assignments are performed as follows: 


1. First to be evaluated are subscripts, POSITION attribute expressions, locator 
qualifications of the target variables, and the second and third arguments of 
SUBSTR pseudovariable references. 


2. The expression on the right-hand side is then evaluated. 

3. For each target variabie (in iefi to right order), the expression is converted to 
the characteristics of the target variable according to the rules for data conver- 
sion. The converted value is then assigned to the target variable. 


Aggregate assignments 
Aggregate assignments (array and structure assignments) are expanded into a 
series of element assignments as follows: 


1. The label prefix of the original statement is applied to a null statement pre- 
ceding the other generated statements. 


2. Array and structure assignments, when there are more than one, are done iter- 
atively. 


3. Any assignment statement can be generated by a previous array or structure 
assignment. The first target variable in an aggregate assignment is known as 
the master variable. (It can also be the first argument of a pseudovariable). If 
the master variable is an array, an array expansion is performed; otherwise, a 
structure expansion is performed. 


4. If an aggregate assignment meets a certain set of conditions, it can be done as 
a whole instead of being expanded into a series of element assignments. Two 
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conditions are if the arrays are not interleaved, or if the structures are contig- 
uous and have the same format. 


In array assignments, all array operands must have the same number of dimen- 
sions and identical bounds. The array assignment is expanded into a loop as 
follows: 


do Jl = lbound(Master-variable,1) to 
hbound(Master-variable, 1); 
do J2 = lbound(Master-variable,2) to 


hbound(Master-variable,2); 


do jn = |bound(Master-variable,n) to 
hbound(Master-variable,n); 


generated assignment statement 


end; 


In this expansion, n is the number of dimensions of the master variable that are to 
participate in the assignment. In the generated assignment statement, all array 
operands are fully subscripted, using (from left to right) the dummy variables j1 to 
jn. If an array operand appears with no subscripts, it will only have the subscripts 
jl to jn. If cross-section notation is used, the asterisks are replaced by j1 to jn. If 
the original assignment statement has a condition prefix, the generated assignment 
statement is given this condition prefix. 


If the generated assignment statement is a structure assignment, it is expanded as 
described next. 
In structure assignments where the BY NAME option is not specified: 


* None of the operands can be arrays, although they can be structures that 
contain arrays. 


* All of the structure operands must have the same number, k, of immediately 
contained items. 


* The assignment statement is replaced by k generated assignment statements. 


— The ith generated assignment statement is derived from the original assign- 
ment statement by replacing each structure operand by its th contained 
item; such generated assignment statements can require further expansion. 


— All generated assignment statements are given the condition prefix of the 
original statement. 


In structure assignments where the BY NAME option is given, the structure 
assignment is expanded according to the steps below, which can generate further 
array and structure assignments. None of the operands can be arrays. 


1. The first item immediately contained in the master variable is considered. 


2. If each structure operand and target variable has an immediately contained 
item with the same name, an assignment statement is generated as follows: 


a. The statement is derived by replacing each structure operand and target 
variable with its immediately contained item that has this name. If any 
structure contains no such name, no statement is generated. 


b. If the generated assignment is a structure or array-of-structures assign- 
ment, BY NAME is appended. 
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c. All generated assignment statements are given the condition prefix of the 
original assignment statement. 


d. A target structure must not contain unions. 


3. Step 2 is repeated for each of the items immediately contained in the master 
variable. The assignments are generated in the order of the items contained in 
the master variable. 


Multiple assignments 
Assignments can be made to multiple variables in a single assignment statement. 
For example: 


A,X =B+C; 


The value of B + C is assigned to both A and X. In general, it has the same effect 
as the following statements: 


Temporary = B + C; 
A = Temporary; 
X = Temporary; 


The source in the assignment statement must be scalar. If the source is a con- 
stant, it is assigned to each of the targets from left to right. If the source is not a 
constant, it is assigned to a temporary variable, which is then assigned to each of 
the targets from left to right. 


The target can be any reference permitted in a simple assignment. 


BY NAME is not permitted in multiple assignments. 


Example of moving internal data 


The following example of the assignment statement can be used for internal data 
movement. The value of the expression on the right of the assignment symbol is to 
be assigned to the variable on the left. 


NTOT=TOT; 


Example of assigning expression values 
The following example includes an expression whose value is to be assigned to the 
variable on the left of the assignment symbol: 


Av=(Av*Num+Tav*Tnum)/(Num+Tnum ) ; 
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Example of assigning a structure using BY NAME 
The foliowing example illustrates structure assignment using the BY NAME option: 


declare declare declare 
1 one, 1 two, 1 three, 
2 Partl, 2 Partl, 2 Partl, 
3 Red, 3 Blue, 3 Red, 
3 Orange, 3 Green, 3 Blue, 
2 Part2, 3 Red, 3 Brown, 
3 Yellow, 2 Part2, 2 Part2, 
3 Blue, 3 Brown, 3 Yellow, 
3 Green; 3 Yellow; 3 Green; 
I One = Two, by name; 
I One.Partl = Three.Partl, by name; 
LI The first assignment statement is the same as the following: 
One. Partl.Red = Two.Partl.Red; 


One.Part2.Yellow = Two.Part2.Yellow; 


[2] The second assignment statement is the same as the following: 
One.Partl.Red = Three.Partl.Red; 


Yassignment statement 


The %assignment macro facility statement is discussed in “%assignment” on 
page 454. 


BEGIN statement 


The BEGIN statement is described in Chapter 6, “Program organization” on 
page 89. 


CALL statement 
The CALL statement is described in “CALL statement” on page 120. 


CLOSE statement 
The CLOSE statement is described in Chapter 10, “Input and output” on page 228. 


%DEACTIVATE statement 
The DEACTIVATE statement is described in “%“DEACTIVATE” on page 454. 


DECLARE statement 
The DECLARE statement is described in “DECLARE statement” on page 129. 
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%DECLARE statement 


The %DECLARE macro facility statement is discussed in “%DECLARE” on 
page 455. 


DEFAULT statement 
The DEFAULT statement is described in “DEFAULT statement” on page 142. 


DELAY statement 
The DELAY statement suspends the execution of the next statement in the applica- 
tion program for the specified period of time. 


The syntax for the DELAY statement is: 


BUA a x 


expression 
specifies an expression that is evaluated and converted to FIXED 
BIN(M,0). Execution is suspended for the number of milliseconds speci- 
fied. 


The maximum wait time is 23 hours and 59 minutes. 


For example: 


delay (20); 
suspends execution for 20 milliseconds. 
delay (10**3); 

suspends execution for 1 
) ° 


delay (10*10**3 


suspends execution for 10 seconds. 


eAaAnn 
oeCcvuVvi 


’ 


DELETE statement 
. The DELETE statement is described in “DELETE statement” on page 245. 


DISPLAY statement 


The DISPLAY statement displays a message on the user's screen and optionally 
requests the user to enter a response to the message. 


The syntax for the DISPLAY statement is: 


>>—DISPLAY—( pO ee eae oe < 
REPLY—( char-ref) 
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DO 


expression 
is converted, where necessary, to a character string. !his characier string 
is displayed. It can contain mixed character data. If the expression has 
the GRAPHIC attribute, it is not converted. | 


REPLY (char-ref) 
specifies a character variable that receives the user entered response. 
You cannot use pseudovariables. The response can contain CHAR- 
ACTER, GRAPHIC, or mixed data. 


The REPLY option will suspend program execution until the user enters a 
response. In some environments (for example, OS/2 Presentation Manager), the 
DISPLAY statement, even without the REPLY option, suspends execution of the 
application until the user acknowledges the message. 


lf GRAPHIC data is entered in the REPLY, it is received as character data that 
contains mixed data. Such character data can be converted to GRAPHIC data 
using the GRAPHIC BUILTIN. 


Example: 
display ('Communication link established.'); 


displays the message 
Communication link established. 


The DO statement and its corresponding END statement, delimit a group of state- 
ments collectively called a do-group. 


Note: Condition prefixes are invalid on DO statements. 
The syntax for the DO statement is: 


Notes: 
1. expn is an abbreviation for expression n. 


2. Condition prefixes are invalid on DO statements. 


Type 1 
| >>—D0—; < | 


Type 2 


r>>—D0 WHILE—(—exp4— ) a 
“ih UNTIL—(—exp5—) 
UNTIL—(—exp5—) 
WHILE—(—exp4—) 
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Type 1 


Types 2 and 3 


Type 3 





r>>—D0—reference— = =m specification i 


specification: 


WHILE—(—exp4—) 


UNTIL—(—exp5—) 
UNT IL—(—exp5—) 
WHILE—(—exp4—) 


Type 4 
>>—DO LOOP—; AA _—______________________» « 


expn 
an abbreviation for expression n 


The type 1 do-group specifies that the statements in the group are executed. It 
does not provide for the repetitive execution of the statements within the group. 


Types 2 and 3 provide for the repetitive execution of the statements within the do- 
group. 


specifies that, before each repetition of do-group, exp4 is evaluated and, if 
necessary, converted to a bit string. If any bit in the resulting string is 1, 
the do-group is executed. If all bits are 0, or the string is null, execution of 
the Type 2 do-group is terminated. For Type 3, only the execution associ- 
ated with the specification containing the WHILE option is terminated. 
Execution for the next specification, if one exists, then begins. 


UNTIL (exp5) 
specifies that, after each repetition of do-group, exp5 is evaluated, and, if 
necessary, converted to a bit string. If all the bits in the resulting string 
are O, or the string is null, the next iteration of the do-group is executed. If 
any bit is 1, execution of the Type 2 do-group is terminated. For Type 3, 
only the execution associated with the specification containing the UNTIL 
option is terminated. Execution for the next specification, if one exists, 
then begins. 


reference 
Pseudovariables cannot be used as a reference. All data types are 
allowed. 


The generation, g, of a reference is established once at the beginning of 
the do-group, immediately before the initial value expression (exp1) is 
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evaluated. If the reference generation is changed to h in the do-group, the 
do-group continues to execute with the reference derived froiii thie gener- 
ation g. However, any reference to the reference inside the do-group is a 
reference to generation h. It is an error to free generation g in the do- 
group. 


If a reference is made to a reference after the last iteration is completed, 
the value of the variable is the value that was out of range of the limit set 
in the specification. That is, if: 


* The BY value is positive and the reference is greater than the TO 
value 
* The BY value is negative and the reference is less than the TO value 


of the limit set in the specification. 


If reference is a program-control data variable other than a locator, the BY 
and TO options cannot be used in specification. 


exp1 specifies the initial value of the reference. 


lf TO, BY, and REPEAT are all omitted from a specification, there is a 
single execution of the do-group, with the reference having the value of 
exp1. If WHILE(exp4) is included, the single execution does not take 
place unless exp4 is true. 


TO exp2 
exp2 is evaluated at entry to the specification and saved. This saved 
value specifies the terminating value of the reference. Execution of the 
statements in a do-group terminates for a specification as soon as the 
value of the reference, when tested at the end of the do-group, is out of 
range. Execution of the next specification, if one exists, then begins. 


lf TO exp2 is omitted from a specification, and if BY exp3 is specified, 
repetitive execution continues until it is terminated by the WHILE or UNTIL 
option, or until another statement transfers control out of the do-group. 


BY exp3 
exp3 is evaluated at entry to the specification and saved. This saved 
value specifies the increment to be added to the reference after each exe- 
cution of the do-group. 


If BY exp3 is omitted from a specification, and if TO exp2 is specified, 
exp3 defaults to 1. 


lf BY O is specified, the execution of the do-group continues indefinitely 
unless it is halted by a WHILE or UNTIL option, or control is transferred to 
a point outside the do-group. 


REPEAT exp6 
exp6 is evaluated and assigned to the reference after each execution of 
the do-group. Repetitive execution continues until it is terminated by the 
WHILE or UNTIL option, or another statement transfers control out of the 
do-group. 


The following sections give more information about using Type 2 and Type 3 DO 
groups. Examples of DO groups begin on page 179. 
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Using type 2 WHILE and UNTIL 

If a Type 2 DO specification includes both the WHILE and UNTIL option, the DO 
statement provides for repetitive execution as defined by the following: 

Label: do while (exp4) 


until Cexp5) 
statement- 1 


statement-n 
end; 
Next: statement /* Statement following the do group */ 


The above is equivalent to the following expansion: 


Label: if (exp4) then; 
else 
go to Next; 
statement -1 


statement-n 
Label2: if (exp5) then; 
else 
go to Label; 
Next: statement /* Statement following the do group */ 


If the WHILE option is omitted, the IF statement at label Label is replaced by a null 
statemen Note that if the WHILE option is omitted, statements 1 through n are exe- 
cuted at least once. 


If the UNTIL option is omitted, the IF statement at label Label2 in the expansion is 
replaced by the statement GO TO Label. 


Using type 3 with one specification 
The following sequence of events summarizes the effect of executing a do-group 
with one specification: 


1. tf reference is specified and BY and TO options are also specified, exp1, exp2, 
and exp3 will be evaluated prior to the assignment of exp7 to the reference. 
Then the initial value is assigned to reference. For example: 


do reference = expl to exp2 by exp3; 

For a variable that is not a pseudovariable, the above action of the do-group 
definition is equivalent to the following expansion: 

el=expl; 

e2=exp2; 

e3=exp3; 

V=E1; 

The variable v is a compiler-created based variable with the same attributes as 
the reference. el, e2, and e3 are compiler-created variables. 


2. If the TO option is present, test the value of the control variable against the 
previously-evaluated expression (e2) in the TO option. 


3. If the WHILE option is specified, evaluate the expression in the WHILE option. 
If it is false, leave the do-group. 


4. Execute the statements in the do-group. 
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5. If the UNTIL option is specified, evaluate the expression in the UNTIL option. If 
it is true, leave the do-group. 


6. If there is a reference: 


a. If the TO or BY option is specified, add the previously-evaluated exp3 (e3) 
to the reference. 


b. If the REPEAT option is specified, evaluate the exp6 and assign it to the 
reference. 


c. If the TO, BY, and REPEAT options are all absent, leave the do-group. 
7. Go to 2 on page 176. 


Using type 3 with two or more specifications 

If the DO statement contains more than one specification, the second expansion is 
analogous to the first expansion in every respect. However, the statements in the 
do-group are not actually duplicated in the program. A succeeding specification is 
executed only after the preceding specification has been terminated. 


When execution of the last specification terminates, control passes to the statement 
following the do-group. 


Control can transfer into a do-group from outside the do-group only if the do-group 
is delimited by the DO statement in Type 1. Control can also return to a do-group 
from a procedure or ON-unit invoked from within that do-group. 


Using type 3 with TO, BY, REPEAT 

The TO and BY options let you vary the reference in fixed positive or negative 
increments. In contrast, the REPEAT option, which is an alternative to the TO and 
BY options, lets you vary the control variable nonlinearly. The REPEAT option can 
also be used for nonarithmetic control variables (such as pointer). 


If the Type 3 DO specification includes the TO and BY options, the action of the 
do-group is defined by the following: 


Label: do variable= 
expl 
to exp2 
by exp3 
while (exp4) 
until¢exp5); 
statement -1 


statement -m 
Labell: end; 
Next: statement 
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The action of the previous do-group definition is equivalent to the following expan- 
sion. In this expansion, v is a compiler-created variable with the same attributes as 
variable; and el, e2, and e3 are compiler-created variables: 


Label: el=expl; 


e2=exp2; 

e3=exp3; 

V=el; : 

Label2: if (e3>=0)&(v>e2)1(e3<0)&(v<e2) then 

go to Next; 

if (exp4) then; 
else 
go to Next; 


statement-1 


statement-m 
Labell: if (exp5) then 
go to Next; 
Label3: V=Vte3; 
go to Label2; 
Next: statement 


If the specification includes the REPEAT option, the action of the do-group is 
defined by the following: 


Label: do variable= 
expl 
repeat expo 
while (exp4) 
until(Cexp5); 
statement -1 


statement-m 
Labell: end; 
Next: statement 


The action of the previous do-group definition is equivalent to the following expan- 
sion: . 


Label: el=expl; 
V=el; 
Label2: ; 
if (exp4) then; 
else 
go to Next; 
statement-1 


Sstatement-m 
Labell: if (exp5) then 
go to Next; 
Label3: V=exp6; 
go to Label2; 
Next: statement 
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Additional rules for the sample expansions are as follows: 


1. The previous expansion only shows the result of one specification. If the DO 
statement contains more than one specification, the statement labeled NEXT is 
the first statement in the expansion for the next specification. The second 
expansion is analogous to the first expansion in every respect. Note, however, 
that statements 1 through m are not actually duplicated in the program. 


2. If the WHILE clause is omitted, the IF statement immediately preceding 
statement-1 in each of the expansions is also omitted. 


3. If the UNTIL clause is omitted, the IF statement immediately following 
statement-m in each of the expansions is also omitted. 


Type 4 
LOOP _specifies infinite iteration. FOREVER is a synonym of LOOP. 
The only way to exit this loop is by a LEAVE or GO TO, or by terminating 
a procedure or the program. 
For example: 


dcl payroll file; 
dcl 1 payrec, 
2 type char, 
2 subtype char, 
2 * char(100); 


Readfile: 
Do loop; 


Read file(payroll) into(payrec); 


it payrecetype = *E 
then leave; /* like goto After_ReadFile */ 


If payrec.type = ‘1’ then 
Do; 
/* process first part of record */ 


If payrec.subtype = 'S' 
then iterate Readfile; /* like goto End_ReadFile */ 


/* process remainder of record */ 
End; 


End_ReadFile: 
End; 
After_ReadFile:; 


Examples of basic repetitions 


In the following example, the do-group is executed ten times, while the value of the 
reference I progresses from 1 through 10. 


do Jo= lb to 18: 


end; 
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The effect of this DO and END statement is equivalent to: 


I=1; 
A: if I > 10 then go to B; 


T=] +1; 
go to A; 
B: next statement 


The following DO statement executes the do-group three times: once for each 
assignment of 'Tom', 'Dick', and 'Harry' to Name. 


do Name = 'Tom', 'Dick', ‘Harry’; 


The following statement specifies that the do-group executes thirteen times: ten 
times with the value of I equal to 1 through 10, and three times with the value of I 
equal to 13 through 15: 


do I = 1 to 10, 13 to 15; 


Repetition using the reference as a subscript 

The reference of a DO statement can be used as a subscript in statements within 
the do-group, so that each execution deals with successive elements of a table or 
array. 


In the following example, the first ten elements of A are set to 1 through 10 in 


sequence: 

do I = 1 to 10; 
ACI) = 1; 

end; 


Repetition with TO and BY 
The following example specifies that the do-group is executed five times, with the 
value of I equal to 2, 4, 6, 8, and 10: 


do I = 2 to 10 by 2; 


If negative increments of the reference are required, the BY option must be used. 
For example, the following is executed with I equal to 10, 8, 6, 4, 2, 0, and -2: 


do I = 10 to -2 by -2; 

In the following example, the do-group is executed with I equal to 1, 3, 5: 
l=2; 

do I=1 to I+3 by I; 

end; 

It is equivalent to the following: 

do I=1 to 5 by 2; 


end; 
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Example of DO with WHILE, UNTIL 


The WHILE and UNTIL options make successive executions of the do-group 
dependent upon a specified condition. For example: 


do while (A=B): 


end; 
is equivalent to the following: 


S: if A=B then; 
else goto R; 


goto S; 
R: next statement 
The example: 
do until (A=B); 


end; 


is equivalent to the following: 
St 


if (A=B) then goto R; 
goto S; 
R: next statement 


In the absence of other options, a do-group headed by a DO UNTIL statement is 
executed at least once, but a do-group headed by a DO WHILE statement might 
not be executed at all. That is, the statements DO WHILE (A=B) and DO UNTIL 
(A4=B) are not equivalent. 


In the following example, if An=B when the DO statement is first encountered, the 
do-group is not executed at all. 


do while(A=B) until (X=10); 
However, if A=B, the do-group is executed. If X=10 after an execution of the do- 


group, no further executions are performed. Otherwise, a further execution is per- 
formed provided that A is still equal to B. 


In the following example, the do-group is executed at least once, with I equal to 1: 
do I=1 to 10 until(Y=1); 

If Y=1 after an execution of the do-group, no further executions are performed. Oth- 
erwise, the default increment (BY 1) is added to I, and the new value of I is com- 


pared with 10. If I is greater than 10, no further executions are performed. 
Otherwise, a new execution commences. 


The following statement specifies that the do-group executes ten times while C(1) 
is less than zero, and then (provided that A is equal to B) once more: 


do I = 1 to 10 while (C(1)<0), 
11 while (A = B); 
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In the following example, the do-group is executed with I equal to 1, 2, 4, 8, 16, 
and so on: 


do I = 1 repeat 2*1; 
end; 


This is equivalent to the following: 


I=1; 

A: 
[=2*1 : 
goto A; 


In the following example, the first execution of the do-group is performed with I=1. 
do I=] repeat 2*I until(1=256); 


After this and each subsequent execution of the do-group, the UNTIL expression is 
tested. If 1=256, no further executions are performed. Otherwise, the REPEAT 
expression is evaluated and assigned to I, and a new execution commences. 


The following example shows a DO statement used to locate a specific item in a 
chained list: 
do P=Phead repeat P -> Fwd 
while(P7=null1()) 
until(P->Id=Id_to_be_ found); 
end; 


The value Phead is assigned to P for the first execution of the do-group. Before 
each subsequent execution, the value P -> Fwd is assigned to P. The value of P is 
tested before the first and each subsequent execution of the do-group. If it is null, 
no further executions are performed. — 


The following statement specifies that the do-group is to be executed nine times, 
with the value of I equal to 1 through 9; then successively with the value of I equal 
to 10, 20, 40, and so on. Execution ceases when the do-group has been executed 
with a value of I greater than 10000. 


do I = 1 to 9, 10 repeat 2*1 
until (1>10000); 
end: 
%DO statement 
The %DO macro facility statement is discussed in “%DO” on page 455. 
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END siatemeni 
The END statement ends a DO, SELECT, PACKAGE, BEGIN or PROCEDURE. 
Every block or group must have an END statement. 


The syntax for the END statement is: 


ccc Doe Daren ar ome | ea a 
statement -label 


statement-label 
cannot be subscripted. If a statement-label follows END, the END state- 
ment closes the unclosed group or block headed by the nearest preceding 
DO, SELECT, PACKAGE, BEGIN, or PROCEDURE statement having that 
statement-label. Every block with a DO, SELECT, PACKAGE, BEGIN or 
PROCEDURE statement must have a corresponding END statement. 


lf a statement-label does not follow END, the END statement closes the 
One group or block headed by the nearest preceding DO, SELECT, 
PACKAGE, BEGIN, or PROCEDURE statement for which there is no other 
corresponding END statement. 


Execution of a block terminates when control reaches the END statement for the 
block. However, it is not the only means of terminating a block's execution, even 
though each block must have an END statement. (See Chapter 6, “Program 
organization” on page 89 for more details.) 


If control reaches an END statement for a procedure, it is treated as a RETURN 
statement. 


Normal termination of a program occurs when control reaches the END statement 
of the main procedure. 


%END statement 


The %END macro facility statement is discussed in “%END” on page 456. 


EXIT statement 


The EXIT statement is identical to STOP. Refer to “STOP statement’ on 
page 195. 


FETCH statement | 
The FETCH statement is described in “FETCH statement’ on page 103. 
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FORMAT statement 


The FORMAT statement is described in Chapter 12, “Stream-oriented data 
transmission” on page 252. 


FREE statement 
The FREE statement is described in Chapter 9, “Storage control” on page 198. 


GET statement 


The GET statement is described in Chapter 12, “Stream-oriented data 
transmission” on page 252. 


GO TO statement 


The GO TO statement transfers control to the statement identified by the specified 
label reference. The GO TO statement is an unconditional branch. 


The syntax for the GO TO statement is: 


r>—G0 TO—/ abe]; A  —__—_ > 


Abbreviation: GOTO 


label = specifies a label constant, a label variable, or a function reference that 
returns a label value. Since a label variable can have different values at 
each execution of the GO TO statement, control might not always transfer 
to the same statement. 


if a GO TO statement transfers coniroi from within a biock to a point not contained 
within that block, the block is terminated. If the transfer point is contained in a 
block that did not directly activate the block being terminated, all intervening blocks 
in the activation sequence are also terminated (see “Procedure termination” on 
page 99). 


When a GO TO statement specifies a label constant contained in a block that has 
more than one activation, control is transferred to the activation current when the 
GO TO is executed (see “Recursive procedures” on page 100). 
A GO TO statement cannot transfer control: 

* To an inactive block. Detection of such an error is not guaranteed. 


* From outside a do-group to a statement inside a Type 2 or Type 3 do-group, 
unless the GO TO terminates a procedure or ON-unit invoked from within the 
do-group. 


° To a FORMAT statement. 
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If the destination of the GO TO is specified by a label variable, it can then be used 
as a Switch by assigning iabei consianis to the iabdel variable. tf ihe iabei variable 
is subscripted, the switch can be controlled by varying the subscript. By using label 
variables or function references, quite complex switching can be effected. It is 
usually true, however, that simple control statements are the most efficient. GOTO 
operations from one block to another block hinder many optimizations in the target 


block, unless the target label is the last statement in its block. 


%GO TO statement 


IF statement 


The %GO TO macro facility statement is discussed in “%GO TO” on page 456. 


The IF statement evaluates an expression and controls the flow of execution 
according to the result of that evaluation. The IF statement thus provides a condi- 
tional branch. 


Note: Condition prefixes are invalid on IF and ELSE statements. 


The syntax for the IF statement is: 


»>>—]f—expression—THEN—uni he 4 
ELSE—unit2 


expression 
is evaluated and, if necessary, converted to a bit string. 


When expressions involve the use of the & and/or | operators, they can be 
evaluated in any order. For more information on evaluations of 
expression, see Chapter 4, “Expressions and references” on page 50. 


unit Each unit is either a valid single statement, a group, or a begin block. All 
single statements are considered valid and executable except DECLARE, 
DEFAULT, END, FORMAT, PROCEDURE, or a % statement. If a nonex- 
ecutable statement is used, the result can be unpredictable. Each unit can 
contain statements that specify a transfer of control (for example, GO TO). 
Hence, the normal sequence of the IF statement can be overridden. 


Each unit can be labeled and can have condition prefixes. 


IF is a compound statement. The semicolon terminating the last unit also termi- 
nates the IF statement. 


If any bit in the string expression has the value '1'B, unit? is executed and unit2, if 


present, is ignored. If all bits are '0'B, or the string is null, unit? is ignored and 
unit2, if present, is executed. 
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%IF statement 


IF statements can be nested. That is, either unit can itself be an IF statement, or 
both can be. Since each ELSE is always associated with the innermost unmatched 
IF in the same block or do-group, an ELSE with a null statement might be required 
to specify a desired sequence of control. For example, if B and C are constants, the 
following example: 


if A =B then 
else 
if A=C then 


else 


is equivalent to and would be better coded as: 


select( A ); 
when ( B ) 
when (ray 
end; 


In the following example, if the comparison is true (if A is equal to B), the value of D 
is assigned to C, and the ELSE unit is not executed. 
if A =B then 

Cea: 
else 

CSE: 
If the comparison is false (A is not equal to B), the THEN unit is not executed, and 
the value of E is assigned to C. 


Either the THEN unit or the ELSE unit can contain a statement that transfers 
control, either conditionally or unconditionally. If the THEN unit ends with a GO TO 
statement there is no need to specify an ELSE unit. For example: 

if all(Arrayl = Array2) then 


go to LABEL_1; 
next-statement 


If the expression is true, the GO TO statement of the THEN unit transfers control to 


LABEL_1. If the expression is not true, the THEN unit is not executed and control 
passes to the next statement. 


The %IF macro facility statement is discussed in “%IF” on page 456. 


186 PL/I Package/2 Language Reference 


%INCLUDE 


%INCLUDE statement 


The %INCLUDE statement is used to incorporate external text into the source 
program. 


The syntax for the %INCLUDE statement is: 


pe—z% INCLUDE—member— ; AAA _______—_——_____-> 


member 
specifies the first part of an OS/2 file name. 


The included member can also contain %INCLUDE statements. 


For information on using the %INCLUDE statement in applications, refer to PL// 
Package/2 Programming Guide 


ITERATE statement 


The ITERATE statement transfers control to the END statement that delimits its 
containing iterative do-group. The current iteration completes and the next iter- 
ation, if needed, is started. It is valid only within an iterative do-group. 


The syntax of the ITERATE statement is: 


ee ate eae 4 
label -constant 


label-constant 
Must be the label of a containing do-group. If omitted, control transfers to 
the END statement of the most recent iterative do-group containing the 
ITERATE statement. 


For an example, see “Type 4” on page 179. 


LEAVE statement 


The LEAVE statement transfers control from within a do-group to the statement fol- 
lowing the END statement that delimits the group and terminates the do-group. 
LEAVE is valid only within a do-group. 


The syntax for the LEAVE statement is: 


Pe 4 
label -constant 


label-constant 
must be a label of a containing do-group. The do-group that is left is the 
do-group that has the specified label. If label-constant is omitted, the do- 
group that is left is the group that contains the LEAVE statement. 
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%NOPRINT 


The LEAVE statement and the referenced or implied DO statement must not be in 
different blocks. 


In addition to the following examples, see the example in “Type 4” on page 179. 


Example 
In the following example, the statement leave A; transfers control to statement after 
group A: 
A: doI=1 to 10; 
do J = 1 to 5; 
if X(I,J)=0 then 
leave A; 
else /* ... */ 3 
end; 
Statement within group A; 
end; 


statement after group A; 


LOCATE statement 


The LOCATE statement is described in Chapter 11, “Record-oriented data 
transmission” on page 242. 


%NOPRINT statement 


The %NOPRINT statement causes printing of the source listings to be suspended 
until a %PRINT statement is encountered or until a %POP statement is encount- 
ered that restores the previous %PRINT statement. 


The syntax for the %NOPRINT statement is: 
| >>—ZNOPRINT— 3 -—— A eee | 
MO se 


For an example of the %NOPRINT statement, refer to ““%PUSH statement” on 
page 191. 


%NOTE statement 


The %NOTE statement generates a diagnostic message of specified text and 
severity. 


The syntax for the %NOTE statement is: 


>y>—“*NOTE—(—messag 
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message 
a Chiaracier expression whose value is the required diagnostic message. 


code __a fixed expression whose value indicates the severity of the message, as 
follows: 


Code . Severity 


0 | 
4 W 
8 E 
12 S 
16 U 


If code is omitted, the default is 0. 


If code has a value other than those listed above, a diagnostic message is 
produced and a default value is taken. If the value is less than O or 
greater than 16, severity U is the default. Otherwise, the next lower 
severity is the default. 


Generated messages are filed together with other preprocessor messages. 
Whether or not a particular message is subsequently printed depends upon its 
severity level and the setting of the compiler FLAG option (as described in the PL// 
Package/2 Programming Guide). 


Generated messages of severity U cause immediate termination of preprocessing 
and compilation. Generated messages of severity S, E, or W might cause termi- 
nation of compilation, depending upon the setting of various compiler options. 


DBCS messages can be generated by using mixed data when the GRAPHIC com- 
piler option is in effect. 


null statement 


The null statement causes no operation to be performed and does not modify 
sequential statement execution. It is often used to denote null action for THEN and 
ELSE clauses and for WHEN and OTHERWISE statements. 


The syntax for the null statement is: 


>> — 5 . Fs ._— U0. 0— 00 rrr q 


Ynull statement 
The %null macro facility statement is discussed in “%null” on page 458. 
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%PAGE 


ON statement 
The ON statement is described in Chapter 15, “Condition handling” on page 302. 


OPEN statement 
The OPEN statement is described in Chapter 10, “Input and output” on page 228. 


PACKAGE statement 
The PACKAGE statement is described in “Packages” on page 92. 


%PAGE statement 


The %PAGE statement allows you to start a new page in the compiler source 
listings. 


The syntax for the %PAGE statement is: 


pe — PAGE 3 A ___________+><« 


%POP statement 


The %POP statement allows you to restore the status of the %PRINT and 
%NOPRINT statements saved by the most recent %PUSH statement. 


The most common use of the %PUSH and %POP statements is in included files 
and macros. 


The syntax of the %POP statement is: 


p> —%P0 P— 3; A$ < 


For an example, see “%PUSH statement” on page 191. 


%PRINT statement 


The %PRINT statement causes printing of the source listings to be resumed. 


The syntax for the %PRINT statement is: 


>> —Z*PR INT — ; A eee 


%PRINT is in effect, provided that the relevant compiler options are specified. For 
an example of the %PRINT statement, refer to “%PUSH statement” on page 191. 
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PROCEDURE statement 


The PROCEDURE statement is described in “PROCEDURE statement” on 
page 94. 


% PROCESS statement 


The %PROCESS statement is used to override compiler options. 





r> —apRacEss fp ——————— dy *'" 
compi ler-optio 


The % or * must be the first data byte of a source record. Any number of 
%PROCESS and “PROCESS statements can be specified, but they must all 
appear before the first language element appears. Refer to the PL/I Package/2 
Programming Guide for more information. 


*PROCESS statement 


The *PROCESS statement is a synonym for the %PROCESS statement. For infor- 
mation on the %PROCESS statement, refer to on page 191. 


%PUSH statement 


The %PUSH statement allows you to save the current status of the %PRINT and 
%NOPRINT statements in a “push down” stack on a last-in, first-out basis. You 
can restore this saved status later, also on a last-in, first-out basis, by using the 
%POP statement. 

A common use of %PUSH and %POP statements is in included files and macros. 


The syntax of the %PUSH statement is: 


>> —%PUSH— 3s AA A eee 


In the following example, statements 1, 2, 3, S1, S2, and 4 are printed in the 
listings. All others are not printed. 
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statement 1; 
statement 2; 
%include First; /* statement 3 */ 
First 
















*push; 
mnoprint; 
statement F4; 
statement F5; 
%include Second; /* stmt F6é */ 
Second 






mpush; 
aprint; 
statement S1; 
statement S2; 
“POD ; 





statement F/7; 
*POP ; 


statement 4; 


PUT statement 


The PUT Statement is described in Chapter 12, “Stream-oriented data 
transmission” on page 252. 


READ statement 


The READ statement is described in Chapter 11, “Record-oriented data 
transmission” on page 242. 


RELEASE statement 
The RELEASE statement is described in “RELEASE statement” on page 103. 


RESIGNAL statement 
The RESIGNAL statement is described in “RESIGNAL statement” on page 309. 


RETURN statement 
The RETURN statement is described in “RETURN statement” on page 121. 


REVERT statement 


The REVERT statement is described in Chapter 15, “Condition handling” on 
page 302. 
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REWRITE statement 


The REWRITE statement is described in Chapter 11, “Record-oriented data 
transmission” on page 242. 


SELECT statement 


A select-group provides a multiple path conditional branch. A select-group contains 
a SELECT statement, optionally one or more WHEN statements, optionally an 
OTHERWISE statement, and an END statement. 


Note: Condition prefixes are invalid on SELECT, OTHERWISE, or WHEN state- 
ments. 


The syntax for the select-group is: 


ae 
(exp!) ; 
WHEN(Y-exp2—L) unit; 


"Lommerwise-unittsJ #2. 
OTHERWISE—unit—; 





Abbreviation: OTHER for OTHERWISE 


SELECT (exp1) 
and its corresponding END statement, delimit a group of statements col- 
lectively called a select-group. The expression in the SELECT statement 
is evaluated and its value is saved. 


WHEN (exp2, exp2...) unit 
specifies an expression or expressions that are evaluated and compared 
with the saved value from the SELECT statement. If an expression is 
found that is equal to the saved value, the evaluation of expressions in 
WHEN statements is terminated, and the unit of the associated WHEN 
statement is executed. If no such expression is found, the unit of the 
OTHERWISE statement is executed. 


The WHEN statement must not have a label or condition prefix. 


OTHERWISE unit 
specifies the unit to be executed when every test of the preceding WHEN 
statements fails. 


lf the OTHERWISE statement is omitted and execution of the select-group 
does not result in the selection of a unit, the ERROR condition is raised. 


The OTHERWISE statement must not have a label or condition prefix. 


unit Each unit is either a valid single statement, a group, or a begin block. 
DECLARE, DEFAULT, END, FORMAT, PROCEDURE, and % statement 
statements are not valid. Each unit can contain statements that specify a 
transfer of control (for example, GO TO). Hence, the normal sequence of 
the SELECT statement can be overridden. 


If exp7 is omitted, each exp2 is evaluated and converted, if necessary, to a bit 
string. If any bit in the resulting string is '1'B, the unit of the associated WHEN 
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statement is executed. If all bits are O or the string is null, the unit of the OTHER- 
WISE statement is executed. 


After execution of a unit of a WHEN or OTHERWISE statement, control passes to 
the statement following the select-group, unless the normal flow of control is altered 
within the unit. 


lf exp1 is specified, each exp2 must be such that the comparison expression 
Cexpl) = (exp2) 


has a scalar bit value. 


Array, structure, and union operands cannot be used in either exp7 or exp2. 


Examples 


In the following example, E, £1, and so on, are expressions. When control reaches 
the SELECT statement, the expression E is evaluated and its value is saved. The 
expressions in the WHEN statements are then evaluated in turn (in the order in 
which they appear), and each value is compared with the value of E. 


If a value is found that is equal to the value of E, the action following the corre- 
sponding THEN statement is performed; no further WHEN statement expressions 
are evaluated. 


If none of the expressions in the WHEN statements are equal to the expression in 
the SELECT statement, the action specified after the OTHERWISE statement is 
executed. 


select (e); 
when (el,e2,e3) action-1; 
when (e4,e5) action-2; 
otherwise action-n; 

end; 

Nl: next statement; 


An example of exp7 being omitted is: 


select; 
when (A>B) call Bigger; 
when (A=B) call Same; 
otherwise call Smaller; 
end; 


If a select-group contains no WHEN statements, the action in the OTHERWISE 
statement is executed unconditionally. If the OTHERWISE statement is omitted, 
and execution of the select-group does not result in the selection of a WHEN state- 
ment, the ERROR condition is raised. 


SIGNAL statement 


The SIGNAL statement is described in Chapter 15, “Condition handling” on 
page 302. 
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%SKIP statement 


The %SKIP statement causes the specified number of lines to be left blank in the 
compiler source listings. 


The syntax for the %SKIP statement is: 





pp—ZSKIP ; —____________» « 
Lin) 


=] 


specifies the number of lines to be skipped. It must be an integer in the 
range 1 through 999. If nis omitted, the default is 1. If nis greater than 
the number of lines remaining on the page, the equivalent of a %PAGE 
statement is executed in place of the %SKIP statement. 


STOP statement 


The STOP statement immediately terminates the program. 


The syntax for the STOP statement is: 


me—S OP 3 ee 


Prior to any termination activity, the FINISH condition is raised. On normal return 
from the FINISH ON-unit the program terminates. 


WRITE statement 


The WRITE statement is described in Chapter 11, “Record-oriented data 
transmission” on page 242. 
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Chapter 9. Storage control 


All variables require storage. The attributes specified for a variable describe the 
amount of storage required and how it is interpreted. In the following example a 
reference to X is a reference to a piece of storage that contains a value to be inter- 
preted as fixed-point binary. 


dcl X fixed binary(31,0) automatic; 


Since X is automatic, the storage for it is allocated when its declaring block is acti- 
vated, and the storage remains allocated until the block is deactivated. 


Storage classes, allocation, and deallocation 


Storage allocation is the process of associating an area of storage with a variable 
so that the data item(s) represented by the variable can be recorded internally. 
When storage is associated with a variable, the variable is allocated. Allocation for 
a given variable can take place statically, (before the execution of the program) or 
dynamically (during execution). A variable that is allocated statically remains allo- 
cated for the duration of the application program. A variable that is allocated 
dynamically relinquishes its storage either upon the termination of the block con- 
taining that variable, or at an explicit request from the application. 


The storage class assigned to a variable determines the degree of storage control 
applied to it and the manner in which the variable's storage is allocated and freed. 
There are four storage classes: automatic, static, controlled, and based. You 
assign the storage class using its corresponding attribute in an explicit, implicit, or 
contextual declaration: 


° AUTOMATIC specifies that storage is allocated upon each entry to the block 
that contains the storage declaration. The storage is released when the block 
is exited. If the block is a procedure that is invoked recursively, the previously 
allocated storage is pushed down upon entry; the latest allocation of storage is 
popped up in a recursive procedure when each generation terminates. (Fora 
discussion of push-down and pop-up stacking, see “Recursive procedures” on 
page 100.) 


* STATIC specifies that storage is allocated when the program is loaded. The 
storage is not freed until program execution is completed. The storage for a 
fetched procedure is not freed until the procedure is released. 


* CONTROLLED specifies that you use the ALLOCATE and FREE statements to 
control the allocation and freeing of storage. Multiple allocations of the same 
controlled variable in the same program, without intervening freeing, will stack 
generations of the variable. You can access earlier generations only by freeing 

_ the later ones. 


* BASED, like CONTROLLED, specifies that you control storage allocation and 
freeing. One difference is that multiple allocations are not stacked but are 
available at any time. Each allocation can be identified by the value of a 
pointer variable. Another difference is that based variables can be associated 
with an area of storage and identified by the value of an offset variable. 


Storage class attributes can be declared explicitly for element, array, and major 
structure and union variables. For array and major structure and union variables, 
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Static storage and attribute 


the storage class declared for the variable applies to all of the elements in the array 
or structure or union. 


Storage class attributes cannot be specified for: 


Entry constants 

File constants 

Format constants 

Label constants 

CONDITION conditions 

Members of structures and unions 
Defined data items. 


Allocation of storage for variables is managed by PL/I. You do not specify where in 
storage the allocation is to be made. You can, however, specify that a variable be 
allocated in an existing AREA. For more information, refer to “Area data and 
attribute” on page 211. 


Static storage and attribute 


Variables declared with the STATIC attribute are allocated prior to running a 
program. They remain allocated until the program terminates. The program has no 
control on the allocation of static variables during execution. 


The syntax for the STATIC attribute is: 


>>—S TAT 1[C-—--AN > 


STATIC is the default for external variables, but internal variables can also be 
static. It is also the default for variables declared in a package, outside of any 
procedure. Static variables follow the normal scope rules for the validity of refer- 
ences to them. In the following example the variable X is allocated for the life of 
the program, but it can be referenced only within procedure 8 or any block con- 
tained in B. The variable Y gets the STATIC attribute and is also allocated for the 
life of the program. 


Package: Package exports (*); 
dcl Y char(10); 


A: proc options(main); 
B: proc; 
declare X static internal; 
end B; 
end A; 


G: proc; 
Y = hello’; 
end C; 


end Package; 


If static variables are initialized using the INITIAL attribute, the initial values must be 
restricted expressions. Extent specifications must also be restricted expressions. 
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Automatic storage and attribute 


Automatic variables are allocated on entry to the block in which they are declared. 
They can be reallocated many times during the execution of a program. You 
control their allocation by your design of the block structure. 


The syntax for the AUTOMATIC attribute is: 


»»—AU TOMA T [C¢-— > « 


Abbreviation: AUTO 
AUTOMATIC is the default. Automatic variables are always internal. 


In the following example, Each time procedure B is invoked, the variables X and Y 
are allocated storage. When B terminates, the storage is released, and the values 
X and Y contain are lost. 


A: proc; 


call B; 
Bs. proc: 
declare X,Y auto; 


end B; 
call B; 


The storage that is freed is available for allocation to other variables. Thus, when- 
ever a block (procedure or begin) is active, storage is allocated for all variables 
declared automatic within that block. Whenever a block is inactive, no storage is 
allocated for the automatic variables in that block. Only one allocation of a partic- 
ular automatic variable can exist, except for those procedures that are called 
recursively or by more than one program. 


Extents for automatic variables can be specified as expressions. This means that 
you can allocate a specific amount of storage when you need it. In the following 
example the character string STR has a length defined by the value of the variable N 
when procedure B is invoked. 
A: proc; 

declare N fixed bin; 


Bs proc; 

declare STR char(N); 
If the declare statements are located in the same block, PL/I requires that the vari- 
able N be initialized either to a restricted expression or to an initialized static vari- 
able. In the following example, the length allocated is correct for Str1, but not for 
Str2. PL/I does not resolve this type of declaration dependency. 
dcl N fixed bin (15) init(10), 

M fixed bin (15) init(N), 


Strl char(N), 
Str2 char(M); 
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Coniroiied storage and attribute 
Variables declared as CONTROLLED are allocated only when you specify them in 


an ALLOCATE statement. A controlled variable remains allocated until a FREE 
statement that names the variable is encountered or until the end of the program. 


Controlled variables are partially independent of the program block structure, but 
not completely. The scope of a controlled variable can be internal or external. 
When it is declared as internal, the scope of the variable is the block in which the 
variable is declared and any contained blocks. Any reference to a controlled vari- 
able that is not allocated is in error. 


The syntax for the CONTROLLED attribute is: 


>>—CONTROLLED AAA AA AA > 


Abbreviation: CTL 


In the following example the variable X can be validly referred to within procedure B 
and that part of procedure A that follows execution of the CALL statement. 
AS DrOc: 

dcl X controlled; 

cal}. *Bs 


Be proc; 
allocate X; 


end B; 
end A; 


Generally, controlled variables are useful when a program requires large data 
aggregates with adjustable extents. Statements in the following example allocate 
the exact storage required depending on the input data and free the storage when 
it is no longer required. 

dcl A(M,N) ctl; 

get list(M,N); 

allocate A; 

get list(A); 


free A; 


This method is more efficient than the alternative of setting up a begin block, 
because block activation and termination are not required. 
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ALLOCATE statement for controlled variables 


The ALLOCATE statement allocates storage for controlled variables, independent 
of procedure block boundaries. Controlled parameters may also be allocated. 


The syntax for the ALLOCATE statement for controlled variables is: 


p> —ALLOCATE—*-contro/ led-variabl i 


Abbreviation: ALLOC 


controlled-variable 
a controlled variable must be a level-1 unsubscripted variable. 


Both controlled and based variables can be allocated in the same statement. For 
the syntax of based variables, refer to “ALLOCATE statement for based variables” 
on page 208. 


Bounds for arrays, lengths of strings, and sizes of areas are evaluated at the exe- 
cution of an ALLOCATE statement. A DECLARE statement must specify any nec- 
essary dimension, size, or length attributes for a variable. Any expression taken 
from a DECLARE statement is evaluated at the point of allocation using the condi- 
tions enabled at the ALLOCATE statement. However, names in the expression 
refer to variables whose scope includes the DECLARE or DEFAULT statement. 


Initial values are assigned to a variable upon allocation, if the variable has an 
INITIAL attribute in the DECLARE statement. Expressions in the INITIAL attribute 
are evaluated at the point of allocation, using the conditions enabled at the ALLO- 
CATE statement, although the names are interpreted in the environment of the dec- 
laration. If initialization involves reference to the variable being allocated, the 
reference is to the new generation of the variable. For more information on initial- 
ization, refer to “INITIAL attribute” on page 220. 


Any evaluations performed at the time the ALLOCATE statement is executed (for 
example, evaluation of expressions in an INITIAL attribute) must not be interde- 
pendent. 


If storage for the controlled variable is not available, the STORAGE condition is 
raised. 


FREE statement for controlled variables 


The FREE statement frees the storage allocated for controlled variables. The freed 
storage is then available for other allocations. The previously allocated controlled 
variable is made available, and subsequent references refer to that allocation. 


The syntax for the FREE statement for controlled variables is: 


p> —FREE—Y contro! led-variabl CO 
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controlled-variable 
is a level-1, unsubscripted variable. 


Both based and controlled variables can be freed in the same statement. For the 
syntax of based variables, Refer to “FREE statement for based variables” on 
page 209. 


Implicit freeing 
A controlled variable need not be explicitly freed by a FREE statement. However, it 
is a good practice to explicitly FREE controlled variables. 


All controlled storage is freed at the termination of the program. 


Multiple generations of controlled variables 
An ALLOCATE statement for a variable for which storage was previously allocated 
and not freed pushes down or stacks storage for the variable. This stacking 
creates a new generation of data for the variable. The new generation becomes 
the current generation. The previous generation cannot be directly accessed until 
the current generation has been freed. When storage for this variable is freed, 
using the FREE statement or at termination of the program in which the storage 
was allocated, storage is popped up or removed from the stack. 


Adjustable extents 


Controlled scalars, arrays, and members of structures and unions may have adjust- 
able array extents, string lengths, and area sizes. In the following example, when 
the structure is allocated, A.B has the extent —10 to +10 and A.C is a VARYING 
character string with maximum length 5. 


der dA etl, 
2 B(N:M), 
2 C char(L) varying; 
= -10; 
= 10; 
= 5; 
alloc A; 
free A; 


—~_sz2 


Built-in functions for controlled variables 


The ALLOCATION built-in function can be used to determine the number of gener- 
ations that have been allocated for a given controlled variable. If the variable is not 
allocated, the function returns the value zero. 
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Based storage and attribute 


A declaration of a based variable is a description of the generation: the amount of 
storage required and its attributes. (A based variable does not identify the location 
of a generation in main storage.) A iocator value identifies the location of the gen- 
eration. Any reference to a based variable that is not allocated is in error. 


The syntax for the BASED attribute is: 


>>—BASED < 
( Jocator-reference) 


locator-reference 
identifies the location of the data 


When reference is made to a based variable, the data and alignment attributes 
used are those of the based variable, while the qualifying locator variable identifies 
the location of data. 


A based variable cannot have the EXTERNAL attribute, but a locator reference for 
a based variable can have any storage class, including based. 


A based structure or union can be declared to contain adjustable area sizes, array- 
bounds, and string-length specifications, by using the REFER option. See “REFER 
Option (Self-Defining Data)” on page 210. 


A BASED VARYING string must have a maximum length equal to the maximum 
length of any string upon which it is defined. 

For example: 
declare A char(50 


) 
B char(50) 
Q=addr(B); 


varying based(Q), 
varying; 


A based variable can be used to obtain storage by using the ALLOCATE statement 
or the LOCATE statement. A based variable can also be used to access existing 
data by using the READ statement (with SET option), or the FETCH statement 
(with SET option), or the ADDR built-in function. 


Because a locator variable identifies the location of any generation, you can refer at 
any point in a program to any generation of a based variable by using an appro- 
priate locator value. The following example declares that references to X, except 
when the reference is explicitly qualified, use the locator variable P to locate the 
storage for X. 


dcl X fixed bin based(P); 


The association of a locator reference in this way is not permanent. The locator 
reference can be used to identify locations of other based variables and other 
locator references can be used to identify other generations of the variable X. 

When a based variable is declared without a locator reference, any reference to the 
based variable must always be explicitly locator-qualified. 


In the following example, the arrays A and C refer to the same storage. The ele- 
ments 8 and C(2,1) also refer to the same storage. 
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Locator Data 


dcl A(3,2) character(5) based(P), 
B char(5) based(Q), 
C(3,2) character(5); 

P = addr(C); 

Q = addr(A(2,1)); 


Note: When a based variable is overlaid in this way, no new storage is allocated. 
The based variable uses the same storage as the variable on which it is overlaid 
(C(3,2) in the example). 


You can also use the DEFINED and UNION attributes to overlay variable storage, 
but DEFINED and UNION overlay the storage permanently. When based variables 
are overlaid with a locator reference, the association can be changed at any time in 
the program by assigning a new value to the locator variable. 


For more information on the DEFINED and UNION attributes, refer to “DEFINED 
and POSITION attributes” on page 218, and “Unions” on page 149. 


The INITIAL attribute can be specified for a based variable. The initial values are 
assigned only upon explicit allocation of the based variable with an ALLOCATE or 
LOCATE statement. 


There are two types of locator data: pointer and offset. 


The value of a pointer variable is an address of a location in storage. It can be 
used to qualify a reference to a variable with allocated storage in several different 
locations. 


The value of an offset variable specifies a location within an area variable and 
remains valid when the area is assigned to a different part of storage. 


A locator value can be assigned only to a locator variable. When an offset value is 
assigned to an offset variable, the area variables named in the OFFSET attributes 
are ignored. 


Locator conversion 
Locator data cannot be converted to other data types, except as follows: 


* To and from REAL FIXED BINARY (p,0) by using the BINARYVALUE, 
POINTERVALUE, and OFFSETVALUE built-in functions 


* Between pointer and offset implicitly or explicitly using the POINTER and 
OFFSET built-in functions. 


When an offset variable is used in a reference, it is implicitly converted to a pointer 
value by using the address of the area variable designated in the OFFSET attribute 
and the offset variable. Explicit conversion of an offset to a pointer value is accom- 
plished using the POINTER built-in function. For example, the following statement 
assigns a pointer value to P, giving the location of a based variable, identified by 
offset 0 in area B. 


dcl P pointer, O offset(A),B area; 
P = pointer(0,B); 
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Because the area variable is different from that associated with the offset variable, 
you must ensure that the offset value is valid for the different area. It is valid, for 
example, if area A is assigned to area B prior to the invocation of the function. 


The OFFSET built-in function, in contrast to the POINTER built-in function, returns 
an offset value derived from a given pointer and area. The given pointer value 
must identify the location of a based variable in the given area. 


A pointer value is converted to offset by using the pointer value and the address of 
the area. This conversion is limited to pointer values that relate to addresses within 
the area named in the OFFSET aitribute. 


Except when assigning the NULL or the SYSNULL built-in function value, it is an. 
error to attempt to convert from or to an offset variable that is not associated with 
an area. 


There is no implicit locator conversion in multiple assignments. 


Locator reference 
A locator reference is either a locator variable that can be qualified or subscripted, 
or a function reference that returns a locator value. 


A locator reference can be used in the following ways: 


* As a locator qualifier, in association with a declaration of a based variable 
* In a comparison operation, as in an IF statement 
* As an argument in a procedure reference. 


Because PL/I implicitly converts an offset to a pointer value, offset references can 
be used interchangeably with pointer references. 


Locator qualification 

Locator qualification is the association of one or more locator references with a 
based reference to identify a particular generation of a based variable. This is 
called a locator-qualified reference. The composite symbol —> represents “qualified 
by” or “points to.” 


The syntax for explicit qualified reference is: 





»>—/ocator-reference -> 1 pased- variable 
based-locator-reference -> 


locator-reference 
based-locator-reference 
identify the location of the data. 





In the following example, X is a based variable, P is a locator variable, and 0 is a 
based locator variable. 


alee can ae aa 
The reference means that it is that generation of X that is identified by the based 


locator Q that is also identified by the value of the locator P. X and Q are said to be 
explicitly locator-qualified. 
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When more than one locator qualifier is used, they are evaluated from left to right. 


Reference to a based variable can also be implicitly qualified. The locator refer- 
ence used to determine the generation of a based variable that is implicitly qualified 
is the one declared with the based variable. In the following example, the ALLO- 
CATE statement sets the pointer variable P so that the reference X applies to allo- 
cated storage. 

dcl X fixed bin based(P) init(0); 


allocate X; 
X= xX + 1: 


The references to X in the assignment statement are implicitly locator-qualified by P. 
References to X can also be explicitly locator-qualified as shown in the following 
example. 

The following assignment statements have the same effect as the previous 
example: 

P->X = P->X + 1; 

Q =P; 

Qer Koa UP 2h ae 1s 


Because the locator declared with a based variable can also be based, a chain of 
locator qualifiers can be implied. For example, the following pointer and based var- 
iables can be used: 


declare (P(10),Q) pointer, 
R pointer based (Q), 
V based (P(3)), 
W based (R), 
Y based; 
allocate R,V,W; 


Given the previous declaration and allocation, the following references are valid: 
PCS)! =2.¥ 


> R->W 
> W 


=wo_= 


The first two references are equivalent, and the last three are equivalent. Any ref- 
erence to Y must include a qualifying locator variable. 


Levels of locator qualification 

A pointer that qualifies a based variable represents one level of locator qualification. 
An offset represents two levels because it is implicitly qualified within an area. The 
number of levels is not affected by a locator being subscripted and/or an element of 
a structure or union. In the following example the references X, P -> X, and Q 

-> P -> X represent three levels of locator qualification. 


declare X based (P), 
P pointer based (Q), 
Q offset (A); 
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POINTER variable and attribute 


A pointer variable is declared contextually if it appears in the declaration of a based 
variable, as a locator qualifier, in a BASED attribute, or in the SET option of an 
ALLOCATE, LOCATE, READ, or FETCH statement. It can also be declared explic- 


itly. 
The syntax for the POINTER attribute is: 


>>—PO INTER > « 


Abbreviation: PTR 


The value of a pointer variable that no longer identifies a generation of a based 
variable is undefined (for example, when a based variable has been freed). Before 
_ a reference is made to a pointer-qualified variable, the pointer must have a value. 


Built-in functions for based variables 
The ADDR built-in function returns a pointer value that identifies the first byte of a 
variable. The ENTRYADDR built-in function returns a pointer value that is the 
address of the first executed instruction if the entry were to be invoked. 


Note: The NULL and SYSNULL built-in functions can, but do not necessarily, 
compare equally.. Your application program must not depend on the functions' 
equality. 


ALLOCATE statement for based variables 


The ALLOCATE statement allocates storage for based variables and sets a locator 
variable that can be used to identify the location, independent of procedure block 
boundaries. 


The syntax for the ALLOCATE statement for based variables is: 


isc HS OCAT ES Se pasedivardanl :_—___________» « 
location-reference 


location-reference: 


iNCaraa-varrableye L seri ae 





Abbreviation: ALLOC 


based variable 
is a level-1 unsubscripted variable. 


IN specifies the area variable in which the storage is allocated. For more 
information on areas, refer to “Area data and attribute” on page 211. 


SET specifies a locator variable that is set to the location of the storage allo- 
cated. If the SET option is not specified, the locator used will be that 
specified in the declaration of the based variable. For syntax information 
about declaring based variables, refer to “Based storage and attribute” on 
page 204 and “Locator data” on page 205. 


208 PL/I Package/2 Language Reference 


FREE for based variables 


Both based and controlled variables can be allocated in the same statement. For 
the syntax of conirolied variabies, see “ALLOCATE siatement for controlled 
variables” on page 202. 


Storage is allocated in an area when the IN option is specified or the SET option 
specifies an offset variable. These options can appear in any order. For allo- 
cations in areas: 


* If sufficient storage for the based variable does not exist within the area, the 
AREA condition is raised. 

* If the IN option is not used when using an offset variable, the declaration of the 
offset variable must specify an area reference. 


When an area is not used, the locator variable must be a pointer variable. If 
storage for the based variable is not available, the STORAGE condition is raised. 


The amount of storage allocated for a based variable depends on its attributes, and 
on its dimensions, length, or size specifications if these are applicable at the time of 
allocation. These attributes are determined from the declaration of the based 


A based structure or union can contain adjustable array bounds or string lengths or 


area sizes (see “REFER Option (Self-Defining Data)” on page 210). The asterisk 
notation for extents is not allowed for based variables. 


FREE statement for based variables 
The FREE statement frees the storage allocated for based and controlled variables. 


The syntax for the FREE statement for based variables is: 


ae one option lias 


option: 


Pil wee a ee ee ee 
locator-reference -> INC area-var7able) 





locator-reference -> 
frees a particular generation of a based variable. The composite symbol 
-> means “qualified by” or “points to.” If the based variable is not explicitly 
locator-qualified, the locator variable declared in the BASED attribute is 
used to identify the generation of data to be freed. If no locator has been 
declared, the statement is in error. 


based variable 
must be a level-1 unsubscripted based variable. 


IN must be specified or the based variable must be qualified by an offset 
declared with an associated area, if the storage to be freed was allocated 
in an area. The IN option cannot appear if the based variable was not 
allocated in an area. Area assignment allocates based storage in the . 
target area. These allocations can be freed by the IN option naming the 
target area. 
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Both based and controlled variables can be freed in the same statement. For the 
syntax of controlled variables, see “FREE statement for controlled variables” on 
page 202. 


A based variable can be used to free storage only if that storage has been allo- 
cated for a based variable having identical data attributes. 


The amount of storage freed depends upon the attributes of the based variable, 
including bounds and/or lengths at the time the storage is freed. The user is 
responsible for determining that this amount coincides with the amount allocated. If 
the variable has not been allocated, the results are unpredictable. 


Implicit freeing 
A based variable need not be explicitly freed by a FREE statement, but it is a good 
practice to do so. 


All based storage is freed at the termination of the program. 


REFER Option (Self-Defining Data) 


A self-defining structure or union contains information about its own fields, such as 
the length of a string. A based structure or union can be declared to manipulate 
this data. String lengths, array bounds, and area sizes can all be defined by vari- 
ables, known as the refer object, declared within the structure or union. When the 
structure or union is allocated (by either an ALLOCATE statement or a LOCATE 
statement), the value of an expression is assigned to the refer object variable. For 
any other reference to the structure or union, the value of the refer object is used. 


The REFER option is used in the declaration of a based structure or union to 
specify that, on allocation of the structure or union, the value of an expression is 
assigned to the refer object and represents the length, bound, or size of another 
variable in the structure or union. 


The syntax for a length, bound, or size with a REFER option is: 


>>— express 7on—REFER—( member - variab]e)————_____—_____—_ « 


expression 
The value of this expression defines the length, bound, or size of the 
member when the structure or union is allocated (using ALLOCATE or 
LOCATE). The expression is evaluated and converted to FIXED BINARY 
(M,0). Any variables used as operands in the expression must not belong 
to the structure or union containing the REFER option. 


- 


Subsequent references to the structure or union obtain the REFER option 
member's length, bound, or size from the current value of member-variable 
(refer object). 


member-variable 
The refer object must conform to the following rules: 


® It must be a member of the same level-1 structure or union. 
* It must be REAL FIXED BINARY (p,0). 
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* It cannot be locator-qualified (see “Locator qualification” on page 206) 
or subscripted. 


* It cannot be part of an array. 


* Explicit assignment to it is not allowed. That is, the variable is given 
the NONASSIGNABLE attribute. 


* It must precede all members that have the REFER option. 


In the following example, the declaration specifies that the based structure STR con- 
sists of an array Y and an element X. 
declare 1 STR based(P), 

2 X fixed binary(31,0), 


2 Y (L refer (X)), 
L fixed binary(31,0) init(1000); 


When STR is allocated, the upper bound is set to the current value of L which is 
assigned to X. For any other reference to Y, such as a READ statement that sets P, 
the bound value is taken from X. 


If the INITIAL attribute is specified for the member with the REFER option, initializa- 
tion of the member occurs after the refer object has been assigned its value. 


Any number of REFER options can be used in the declaration of a structure or 
union. 


The value of the refer object should not be changed during program execution. It is 
an error to free such an aggregate if the value of the refer object has changed. 


Area data and attribute 


Area variables describe areas of storage that are reserved for the allocation of 
based variables. This reserved storage can be allocated to, and freed from, based 
variables by the ALLOCATE and FREE statements. Area variables can have any 
storage class and must be aligned. 


When a based variable is allocated and an area is not specified, the storage is 
obtained from wherever it is available. Consequently, allocated based variables 
can be scattered widely throughout main storage. This is not significant for internal 
operations because items are readily accessed using the pointers. However, if 
these allocations are transmitted to a data set, the items have to be collected 
together. Items allocated within an area variable are already collected and can be 
transmitted or assigned as a unit while still retaining their separate identities. 


You might want to identify the locations of based variables within an area variable 
relative to the start of the area variable. Offset variables are provided for this 
purpose. 


An area can be assigned or transmitted complete with its contained allocations; 
thus, a set of based allocations can be treated as one unit for assignment and 
input/output while each allocation retains its individual identity. 


The size of an area is adjustable in the same way as a string length or an array 


bound and therefore it can be specified by an expression or an asterisk (for a con- 
trolled area parameter) or by a REFER option (for a based area). 
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A variable is given the AREA attribute contextually by its appearance in the 
OFFSET attribute or an IN option, or by explicit declaration. 


The syntax for the AREA attribute is: 


" pP—AREA 3 < 
oe 
(expressTo ) 


REFER( var7ab/e) 





expression 
specifies the size of the area. If expression, or an asterisk is not specified, 
the default is 1000. 


* An asterisk can be used to specify the size if the area variable is declared 
is a parameter. 


REFER For a description of the REFER option, refer to “REFER Option (Self- 
Defining Data)” on page 210. 


The area size for areas that have the storage classes AUTOMATIC or CON- 
TROLLED is given by an expression whose value specifies the number of reserved 
bytes. 


If an area has the BASED attribute, the area size must be a constant unless the 
area is a member of a based structure or union and the REFER option is used. 


The size for areas of static storage class must be specified as a restricted 
expression. 


Examples of AREA declarations are: 


declare areal area(2000), 
area2 area; 


In addition to the declared size, an extra 16 bytes of control information precedes 
the reserved size of an area. The 16 bytes contain such details as the amount of 
storage in use. 


The amount of reserved storage that is actually in use is known as the extent of the 
area. When an area variable is allocated, it is empty, that is, the area extent is 
zero. The maximum extent is represented by the area size. Based variables can 
be allocated and freed within an area at any time during execution, thus varying the 
extent of an area. 


When a based variable is freed, the storage it occupied is available for other allo- 
cations. A chain of available storage within an area is maintained; the head of the 
chain is held within the control information. Inevitably, as based variables with dif- 
ferent storage requirements are allocated and freed, gaps will occur in the area 
when allocations do not fit available spaces. These gaps are included in the extent 
of the area. 


No operators, including comparison, can be applied to area variables. 
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Offset data and attribute 


Offset data is used exclusively with area variables. The value of an offset variable 
indicates the location of a based variable within an area variable relative to the start 
of the area. Because the based variables are located relatively, if the area variable 
is assigned to a different part of main storage, the offset values remain valid. 


Offset variables do not preclude the use of pointer variables within an area. The 
syntax for the OFFSET attribute is: 


p>>——OF FSET < 
(—area-variable—) 


The association of an area variable with an offset variable is not permanent. An 
offset variable can be associated with any area variable by means of the POINTER 

_ built-in function (see “Locator conversion” on page 205). The advantage of making 
such an association in a declaration is that a reference to the offset variable implies 
reference to the associated area variable. If no area variable is specified, the offset 
can be used as a locator qualifier only through use of the POINTER built-in func- 
tion. 


Setting offset variables 
The value of an offset variable can be set in any one of the following ways: 


°* By an ALLOCATE statement 


* By assignment of the value of another locator variable, or a locator value 
returned by a user-defined function 


° The NULL, SYSNULL, ADDR, ENTRYADDR, OFFSETADD, 
OFFSETSUBTRACT, OFFSETVALUE, or OFFSET built-in function 


If no area variable is specified, the offset can be used only as a locator qualifier 
through use of the POINTER built-in function. 


Examples of offset variables 
Consider the following example: 


dcl X based(0), 
Y based(P), 
A area, 
0 offset(A); 


allocate X; 
allocate Y in(A); 


The storage class of area A and offset O is AUTOMATIC by default. The first 
ALLOCATE statement is equivalent to: 


ALLOCATE X INCA) SET(O); 


The second ALLOCATE statement is equivalent to: 
ALLOCATE Y INCA) SET(P); 
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The following example shows how a list can be built in an area variable using offset 
variables: 


dcl A area, 
(T,H) offset(A), 
i STR based(H), 
2 P offset(A), 
2 data; 


allocate STR in(A); 
T=H; 


do loop; 


allocate STR set(T->P); 
T=T->P: 


end; 


Area assignment 


The value of an area reference can be assigned to one or more area variables by 
an assignment statement. Area-to-area assignment has the effect of freeing all 
allocations in the target area and then assigning the extent of the source area to 
the target area, so that all offsets for the source area are valid for the target area. 
In the following example: 


declare X based (0(1)), 
0(2) offset (A), 


(A,B) area; 
alloc X in (A); 
X= 1; 
alloc X in (A) set (0(2)); 
OO nS ee 
B=A; 
Using the POINTER ouilt-in function, the references POINTER (0(2),B)->X and 
(2)->X represent the same value allocated in areas B and A respectively. 


If an area containing no allocations is assigned to a target area, the effect is to free 
all allocations in the target area. 


Area assignment can be used to expand a list of based variables beyond the 
bounds of its original area. If you attempt to allocate a based variable within an 
area that contains, insufficient free storage to accommodate it, the AREA condition 
is raised. The ON-unit for this condition can be to change the value of a pointer 
qualifying the reference to the inadequate area, so that it points to a different area; 
on return from the ON-unit, the allocation is attempted again, within the new area. 
Alternatively, the ON-unit can write out the area and reset it to EMPTY. 


Input/output of areas 


Areas allow input and output of complete lists of based variables as one unit, to 
and from RECORD files. On output, the area extent, together with the 16 bytes of 
control information, is transmitted, except when the area is in a structure or union 
and is not the last item in it—then, the declared size is transmitted. Thus the 
unused part of an area does not take up space on the data set. 
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Because the extents of areas can vary, varying length records should be used. 
The maximum record length required is governed by the area length (area size + 
16). 


List processing 


List processing is the name for a number of techniques to help manipulate col- 
lections of data. Although arrays, structures, and unions are also used for manipu- 
lating collections of data, list processing techniques are more flexible since they 
allow collections of data to be indefinitely reordered and extended during program 
execution. The purpose here is not to illustrate these techniques but is to show 
how based variables and locator variables serve as a basis for this type of proc- 
essing. 


In list processing, a number of based variables with many generations can be 
included in a list. Members of the list are linked together by one or more pointers 
in one member identifying the location of other members or lists. The allocation of 
a based variable cannot specify where in main storage the variable is to be allo- 
cated (except that you can specify the area that you want it allocated in). In prac- 
tice, a chain of items can be scattered throughout main storage, but by accessing 
each pointer the next member is found. A member of a list is usually a structure or 
union that includes a pointer variable. 

The following example creates a list of structures: 


dcl 1 STR based(H), 
2 P pointer, 
2 data, 
T pointer; 


allocate STR; 
T=H; 


do loop; 
allocate STR set(T->P); 
T=I->P; 
T->P=null; 


end: 


The structures are generations of STR and are linked by the pointer variable P in 
each generation. The pointer variable T identifies the previous generation during 
the creation of the list. The first ALLOCATE statement sets the pointer H to identify 
it. The pointer H identifies the start, or head, of the list. The second ALLOCATE 
statement sets the pointer P in the previous generation to identify the location of 
this new generation. The assignment statement T=T->P; updates pointer T to iden- 
tify the location of the new generation. The assignment statement T->P=NULL; sets 
the pointer in the last generation to NULL, giving a positive indication of the end of 
the list. 


Figure 38 on page 216 shows a diagrammatic representation of a one-directional 
chain. 
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Data l | 


Figure 38. Example of One-Directional Chain 





Unless the value of P in each generation is assigned to a separate pointer variable 
for each generation, the generations of STR can be accessed only in the order in 
which the list was created. For the above example, the following statements can 
be used to access each generation in turn: 
do T=H 

repeat(T->P) 

while (T-=nul1); 


~ Lorddte. cat 
end; 


The foregoing examples show a simple list processing technique, the creation of a 
unidirectional list. More complex lists can be formed by adding other pointer vari- 
ables into the structure or union. If a second pointer is added, it can be made to 
point to the previous generation. The list is then bidirectional; from any item in the 
list, the previous and next items can be accessed by using the appropriate pointer 
value. Instead of setting the last pointer value to the value of NULL, it can be set 
to point to the first item in the list, creating a ring or circular list. 


A list need not consist only of generations of a single based variable. Generations 
of different based structure or unions can be included in a list by setting the appro- 
priate pointer values. Items can be added and deleted from a list by manipulating 
tne vaiues of pointers. A list can be restructured by manipulating the pointers so 
that the processing of data in the list can be simplified. 


ASSIGNABLE and NONASSIGNABLE attributes 


The ASSIGNABLE and NONASSIGNABLE attributes specify whether the associ- 
ated variable can be the target of an assignment. 


The syntax for the ASSIGNABLE and NONASSIGNABLE attributes is: 


ASSTGNABLE 
>> —L NONASSTGNABLE < 


Abbreviations: ASGN, NONASGN 
Default: ASSIGNABLE 


If a variable has the NONASSIGNABLE attribute, the variable cannot be assigned 
to. 
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If an entry descriptor has the NONASSIGNABLE attribute, the argument is 
assumed not to change when the associaied ENTRY is ivivoked. if the argument is 
a constant, no dummy argument is created. 


The ASSIGNABLE and NONASSIGNABLE attributes are propagated to members 
of structures or unions. 


NORMAL and ABNORMAL attributes 


The NORMAL and ABNORMAL attributes specify whether the associated variable 
is subject to change any time. 


The ABNORMAL attribute specifies that the value of the variable can change 
between statements or within a statement. An abnormal variable is fetched from or 
stored in storage each time it is needed or each time it is changed. All optimization 
is inhibited for an abnormal variable. 


The syntax for the NORMAL and ABNORMAL attributes is: 
NORMAL 
>» —L ABNORMAL < 


Default: NORMAL 


The NORMAL and ABNORMAL attributes are propagated to members of structures 
or unions. 


CONNECTED and NONCONNECTED attributes 


Elements, arrays, and major structure or unions are always allocated in connected 
storage. References to unconnected storage arise only when you refer to an 
aggregate that is made up of noncontiguous items from a larger aggregate. (See 
“Cross sections of arrays” on page 147.) For example, in the following structure 
the interleaved arrays A.B and A.C are both in unconnected storage. 
1 A(10), 

2B; 

ha 


The syntax for the CONNECTED and UNCONNECTED attributes is: 


NONCONNECTED 
>» —LconnecteD Py 


Abbreviations: CONN, NONCONN 

Default: NONCONNECTED 

The CONNECTED attribute is applicable only to noncontrolled aggregate parame- 
ters and can be specified only on level-1 names. It specifies that the parameter is 


a reference to connected storage only, and therefore, allows the parameter to be 
used as a target or source in record-oriented I/O, or as a base in string overlay 


Chapter 9. Storage control 217 


DEFINED and POSITION 


defining. When the parameter is connected and the CONNECTED attribute is 
used, more efficient object code is produced for references to the connected 
parameter. 


NONCONNECTED must be specified or defaulted if a parameter occupies noncon- 
tiguous storage. In the following example the NONCONNECTED attribute specifies 
that the sum_Slice routine handles 1-dimensional arrays in which the elements may 
not be contiguous. In the first invocation, sum_Slice is passed the first row, which 
is in connected storage. In the second invocation, however, sum_Slice is passed 
the first column, which is in nonconnected storage. 


dcl A(10,10) fixed bin(31); 


display( sum_Slice( A(1,*) ) ); /* first row */ 
display( sum_Slice( A(*,1) ) ); /* first column */ 


sum_Slice:proc(X) returns(fixed bin(31)); 


dcl X (*) fixed bin(31) nonconnected; /* default */ 
return(sum(X) ); 
end; 


DEFINED and POSITION attributes 


The DEFINED attribute specifies that the declared variable is associated with some 
or all of the storage associated with the designated base variable. The UNION 
attribute allows you to achieve this and also permits variables with different attri- 
butes and precisions to be overlaid. Another difference is that DEFINED guaran- 
tees that access through defined or base variables is reflected in all defined 
variables. In a union only one member of the union is valid at any given time. For 
syntax information on the UNION attribute, refer to “UNION attribute” on page 149. 


The POSITION attribute, which can be used only with string-overlay defining, speci- 
fies the bit, character, or graphic within the base variable at which the defined vari- 


ree ee ee 


able is io begin. The syniax for the DEFINED attribute is: 
>>—DEFI NED—-re 1g am gC < 
(reference) POSITION( express7on) 


Abbreviation: DEF for DEFINED, POS for POSITION 


reference 

refers to the “base” variable, for which the storage is associated with the 
declared (defined) variable. The base variable can be EXTERNAL or 
INTERNAL. It can be a connected parameter. It cannot be BASED, 
DEFINED or CONTROLLED. A change to the base variable's value is a 
corresponding change to the value of the defined variable, and vice versa. 

_ The base variable can have adjustable extents. It should be specified as 
NONVARYING, with a data type of CHARACTER, BIT, or GRAPHIC. 
Other data types produce unpredictable results. 


expression 
specifies the position relative to the start of the base variable. If the POSI- 
TION attribute is omitted, POSITION(1) is the default. The value specified 
in the expression can range from 1 to N. The value N is defined as 


218 PL/I Package/2 Language Reference 


DEFINED and POSITION 


N = NCB) - NCD) + 1 where N(B) is the number of bits, characters, or 
graphics in the base variabie, and N(U) is the number of bits, characters, 
or graphics in the defined variable. 


The expression is evaluated and converted to an integer value at each 
reference to the defined item. 


When the defined variable is a bit aggregate: 


* The POSITION attribute can contain only a restricted expression. 
* The base variable must not be subscripted. 


The defined variable does not inherit any attributes from the base variable. It can 
have the dimension attribute. The defined variable: 


® Must be INTERNAL and a level-1 identifier 


* Cannot have INITIAL, AUTOMATIC, BASED, CONTROLLED, STATIC, 
PARAMETER, or ALIGNED attributes. 


In references to defined data, the STRINGRANGE, SUBSCRIPTRANGE, and 
STRINGSIZE conditions are raised for the array bounds and string lengths of the 
defined variable, not the base variable. 


Values are determined and names are interpreted as follows: 


* The array bounds, string lengths, and area sizes of a defined variable must be 
known at compile time. 


* A reference to a defined variable is a reference to the current generation of the 
base variable. When a defined variable is passed as an argument without the 
creation of a dummy argument, the corresponding parameter refers to the base 
variable when the argument is passed. 


Both the defined and the base variables must belong to: 


* The bit class, including: 


NONVARYING bit variables 
Aggregates of NONVARYING bit variables. 


°* The character class, including: 


NONVARYING character variables 
Character pictured and numeric pictured variables 
Aggregates of the previous two. 


* The graphic class, including: 
NONVARYING graphic variables 
Aggregates of NONVARYING graphic variables. 


Examples: 


dcl A char(100), 
V¥(10,10) char(1) def A;° 


V is a two-dimensional array that consists of all elements in the character string A. 


dc] B(10) char(1), 
W char(10) def B; 


W is a character string that consists of all the elements in the array B. 
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dcl C char(10), 
X char(4) pos(7) def(C); 


X is a character string representing the 4 rightmost characters of C. 


dc] D(10,10) char(10), 
Y(5,5) char(2) pos(1) def(D), 
Y2(5,2,2) char(2) def(D); 


Y and D match, so the POSITION attribute is required. However, POSITION is not 
required for Y2 because Y2 and D do not match. 


de | tE. 
2 (F,G,H) char(16), 
1 Z def(E) pos(1), 
2-(F GH) chart), 
1 22 def(E), 
2 (F,G,H) char(1), 
2 (I,J) char(1); 


Z and £ match; therefore, POSITION is required. However, 72 and E do not match. 


deh OC16;.10) bitch); 
X bit(40) def(C) pos(20); 


X is a bit string that consists of 40 elements of C, starting at the twentieth element. 


dl: & pic"99V 999". 
Z71(6) char(1) def(E), 
Z2 char(3) def(E) pos(4), 
73(4) char(1) def(E) pos(2); 


Z1 is a character string array that consists of all the elements of the numeric picture 
E. 2Z2 is a character string that consists of the elements '999' of the picture E. 23 
is a character-string array that consists of the elements '9.99' of the picture E. 


dcl AC20) char(10), 
B(10) char(5) def A position(1); 


The first 50 characters of B consist of the first 50 characters of A. POSITION(1) 
must be explicitly specified because A and B match. 


INITIAL attribute 


The INITIAL attribute specifies an initial value or values assigned to a variable at 
the time storage is allocated for it. Only one initial value can be specified for an 
element variable. More than one can be specified for an array variable. A struc- 
ture or union variable can be initialized only by separate initialization of its elemen- 
tary names, whether they are element or array variables. The INITIAL attribute 
cannot be given to constants, defined data, noncontrolled parameters, and 
non-LIMITED static entry variables. 


The INITIAL attribute has two forms. The first form, INITIAL, specifies an initial 
constant, expression, or function reference, for which the value is assigned to a 
variable when storage is allocated to it. The second form, INITIAL CALL, specifies 
(with the CALL option) that a procedure is invoked to perform initialization. The 
variable is initialized by assignment during the execution of the called routine. (The 
routine is not invoked as a function that returns a value to the point of invocation.) 
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The syntax for the INITIAL attribute is: 


p>—INITIAL—(—¥4 item HL) 


item: 
* 


initial -constant 
referenc 
(expression) 
iteration-specification 
iteration-specification: 


+—( iteration-factor)—| iteration-item } —-—————-___—_____________ 


iteration-item: 


initial-constant 


>>— INITIAL ON Feenerierme | [ ¢—— [ 
generic-nam ‘ 
built-in-nam (argument) 


Abbreviations: INIT and INIT CALL 





, specifies that the element is to be left uninitialized. 


iteration factor 
specifies the number of times the iteration item is to be repeated in the 
initialization of elements of an array. 


The iteration factor can be an expression or an asterisk. 


* An expression is converted to FIXED BIN(31). For static variables, it 
must be a constant. 


* An asterisk indicates that the remaining elements should be initialized 
to the specified value. 


A negative or zero iteration factor specifies no initialization. 


constant 
reference 
expression 
specify an initial value to be assigned to the initialized variable. 
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INITIAL CALL 
For INITIAL CALL, the entry reference and argument list passed must 
satisfy the condition stated for block activation as discussed under “Block 
activation” on page 91. 


INITIAL CALL cannot be used to initialize static data. 


The following example initializes all of the elements of A to X'00' without the need 
for the INITIAL attribute on each element: 


dcl 1 A automatic, 
Le es 
G: s haaes 
2 * char(0) initial call plifill( addr(A), 'OO'X, stg(A) ); 
If the procedure invoked by the INITIAL CALL statement has been specified in a 
FETCH or RELEASE statement and it is not present in main storage, the INITIAL 
CALL statement initiates dynamic loading of the procedure. (For more information 
on dynamic loading, refer to “Dynamic loading of an external procedure” on 
page 101.) 


Initializing array variables 


Initial values specified for an array are assigned to successive elements of the 
array in row-major order (final subscript varying most rapidly). If too many initial 
values are specified, the excess values are ignored; if not enough are specified, the 
remainder of the array is not initialized. 


The initialization of an array of strings can include both string repetition and iter- 
ation factors. Where only one of these is given, it is taken to be a string repetition 
factor unless the string constant is placed in parentheses. 


The iteration factor may be specified as *, which means that all of the remaining 
elements will be initialized with the given value. 


_In the following examples: 


iipviwe. 


((2)'A') is equivalent to ('AA") 


((2)('A')) is equivalent to ('A','A') 


((2)(1)'A') is equivalent to ('A’, 'A') 


((*)(1)'A') is equivalent to ('A', 'A’...'A') 


An area variable is initialized with the value of the EMPTY built-in function, on allo- 
cation. Any INITIAL clause for an area variable will be ignored. 


If the attributes of an item in the INITIAL attribute differ from those of the data item 
itself, conversion is performed, provided the attributes are compatible. 


INITIAL is not allowed on objects of REFER clauses. 


If the variable has the REFER option and the item involves a base element or a 
substructure or union of the current generation of the variable, the result of the 
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INITIAL attribute is undefined. In the following example the result of initializing D is 
undefined. 


dcl 1 A based(Q), 
2B fixed bin(15), 
2 C char(N refer(B)) 
initC'AAB'), 
2 D char(5) init(C); 
allocate A; 


Initializing unions | 
The members of a union can have initial values. However, if the union is static, 
only one member of the union can have the initial attribute. For nonstatic unions, 
initial attributes are applied in order of appearance. Subsequent initial values over- 
write previous ones. 


in the following example, the declaration for NT1 would be invalid if it had the static 
storage attribute. However, the declaration for NT2 is valid even though it has static 
storage class. Furthermore, the N72 declaration is portable across EBCDIC and 
ASCII machines. 


dc] 
1 NT1 union automatic, 
2 Numeric_translate_tablel char(256) 
init( (256)'00'X), 

2%, 
3 * char(240), 
3 * char(10) init('0123456789'), 

2 * char(0); . 


dc| 
1 NT2 union static, 
2 Numeric_translate_table2 char(256), 
2%, . 
3 * char( index(collate(),'0')-1 
jnit((1)(Clow(index(collate(),'0')-1 
3 * char(10) init('0123456789'), 
3° * chart (256-(index(collate(),'0')-1)-10) ) 
init((1)Clow( (256-(index(collate(),'0')-1)-10) )) ), 


) 
ee 


Initializing static variables 
For a variable that is allocated when the program is loaded, that is, a static vari- 
able, which remains allocated throughout execution of the program, any value spec- 
ified in an INITIAL attribute is assigned only once. (Static storage for fetched 
procedures is allocated and initialized each time the procedure is loaded.) 


If static variables are initialized using the INITIAL attribute, the initial values must be 


specified as restricted expressions. Extent specifications must be restricted 
expressions. 
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The restrictions on initializing static variables are as follows: 


* STATIC ENTRY variables must have the LIMITED attribute (see “LIMITED 
attribute” on page 117). 


® INITIAL is not allowed for static format variables. 


¢ INITIAL is allowed for label variables that are not part of structures or unions. 
In this case, the label variable gets the CONSTANT attribute. 


® INITIAL is not allowed for static unaligned bit variables with inherited dimen- 
sions, unless initial values are all bit strings consisting solely of zeros. 


* INITIAL is not valid for AREA variables. 
* Only one element of a static union may specify INITIAL. 


° Ifa STATIC EXTERNAL item without the RESERVED attribute is given the 
INITIAL attribute in more than one declaration, the value specified must be the 
same in every case. 


Initializing automatic variables 


For automatic variables, which are allocated at each activation of the declaring 
block, any specified initial value is assigned with each allocation. | 


Initializing based and controlled variables 


For based and controlled variables, which are allocated at the execution of ALLO- 
CATE statements (also LOCATE statements for based variables), any specified 
initial value is assigned with each allocation. 


Examples 
In the following example, when storage is allocated for Name, the character constant 
‘John Doe’ (padded on the right to 10 characters) is assigned to it. 


dcl Name char(10) init('John Doe'); 


In the following example, when Pi is allocated, it is initialized to the value 3.1416. 
dcl Pi fixed dec(5,4) init(3.1416); 


The following example specifies that A is to be initialized with the value of the 
expression B*C: 


declare A init((B*C)); 


The following example results in each of the first 920 elements of A being set to 0. 
The next 80 elements consist of 20 repetitions of the sequence 5,5,5,9. 


declare A (100,10) initial 
((920)0, (20) ((3)5,9)); 


In the following example, only the first, third, and fourth elements of A are initialized; 
the rest of the array is not initialized. The array B is fully initialized, with the first 25 
elements initialized to 0, the next 25 to 1, and the remaining elements to 0. In the 
structure C, where the dimension (8) has been inherited by D and E, only the first 
element of D is initialized. All the elements of E are initialized. 
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declare A(15) character(13) initial 
('John Doe’, 
* 


‘Richard Row', 
"Mary Smith'), 


B (10,10) decimal fixed(5) 
init((25)0,(25)1,(*)0), 


1 CCS), 
2D initial (0), 
2 E initial((*)0); 


When an array of structures or unions is declared with the LIKE attribute to obtain 
the same structuring as a structure or union whose elements have been initialized, 
only the first structure or union is initialized. 


In the following example only J(1).H and J(1).I are initialized in the array of struc- 
tures. 
declare 1 G, 
2H initial(0), 
2 I initial(0), 
PCS) KEG; 
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PL/I input and output statements (such as READ, WRITE, GET, PUT) let you 
transmit data between the main and auxiliary storage of a computer. A collection of 
data external to a program is called a data set. Transmission of data from a data 
set to a program is called input. Transmission of data from a program to a data set 
is called output. (If you are using a terminal, “data set” can also mean your ter- 
minal.) 


PL/I input and output statements are concerned with the logical organization of a 
data set and not with its physical characteristics. A program can be designed 
without specific knowledge of the input/output devices that will be used when the 
program is executed. To allow a source program to deal primarily with the logical 
aspects of data rather than with its physical organization in a data set, PL/I employs 
models of data sets, called files. A file can be associated with different data sets at 
different times during the execution of a program. 


PL/I uses two types of data transmission: stream and record. 


In stream-oriented data transmission, the organization of the data in the data set is 
ignored within the program, and the data is treated as though it were a continuous 
stream of individual data values in character form. Data is converted from char- 
acter form to internal form on input, and from internal form to character form on 
output. 


For more information on stream-oriented data transmission, refer to Chapter 12, 
“Stream-oriented data transmission” on page 252 


Stream-oriented data transmission can be used for processing input data prepared 
in character form and for producing readable output, where editing is required. 
Stream-oriented data transmission allows synchronized communication with the 
program at run time from a terminal, if the program is interactive. 


Stream-oriented data transmission is more versatile than record-oriented data trans- 
mission in its data-formatting abilities, but is less efficient in terms of run time. 


In record-oriented data transmission, the data set is a collection of discrete records. 
The record on the external medium is generally an exact copy of the record as it 
exists in internal storage. No data conversion takes place during record-oriented 
data transmission. On input the data is transmitted exactly as it is recorded in the 
data set, and on output it is transmitted exactly as it is recorded internally. 


For more information on record-oriented data transmission, refer to Chapter 11, 
“Record-oriented data transmission” on page 242 


Record-oriented data transmission can be used for processing files that contain 
data in any representation, such as binary, decimal, or character. 


Record-oriented data transmission is more versatile than stream-oriented data 
transmission, in both the manner in which data can be processed and the types of 
data sets that it can process. Since data is recorded in a data set exactly as it 
appears in main storage, any data type is acceptable, No conversions occur, but 
you must have a greater awareness of the data structure. 
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Data sets 


Consecutive 


Indexed 


Relative 


Data sets 


It is possible for the same data set to be processed at different times by either 
siream or record data transmission. However, ali items in ine daia set musi be in 
character form. 


The following sections in this chapter discuss the kinds of data sets, the attributes 
for describing files, and how you open and close files in order to transmit data. For 
more information about the types of data set organizations that PL/I recognizes, 
refer to PL/| Package/2 Programming Guide. 


In addition to being used as input from and output to your terminal, data sets are 
stored on a variety of auxiliary storage media, including magnetic tape and direct- 
access storage devices (DASDs). Despite their variety, these media have charac- 
teristics that allow common methods of collecting, storing, and transmitting data. 
The organization of a data set determines how data is recorded in a data set and 
how the data is subsequently retrieved so that it can be transmitted to the program. 
Records are stored in and retrieved from a data set either sequentially on the basis 
of successive physical or logical positions, or directly by the use of keys specified in 
data transmission statements. 


PL/I supports the following types of data set organizations: 


Consecutive 
Indexed 
Relative 
Regional 


The data set organizations differ in the way they store data and in the means they 
use to access data. 


In the consecutive data set organization, records are organized solely on the basis 
of their successive physical positions. When the data set is created, records are 
written consecutively in the order in which they are presented. The records can be 
retrieved only in the order in which they were written. 


In the indexed data set organization, records are placed in a logical sequence 
based on the key of each record. An indexed data set must reside on a direct- 
access device. A character string key identifies the record and allows direct 
retrieval, replacement, addition, and deletion of records. Sequential processing is 
also allowed. 


In the relative data set organization, numbered records are placed in a position rel- 
ative to each other. The records are numbered in succession, beginning with one. 
A relative data set must reside on a direct-access device. A key that specifies the 
record number identifies the record and allows direct retrieval, replacement, addi- 
tion, and deletion of records. Sequential processing is also allowed. 
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Files 


Regional 
The regional data set organization is divided into numbered regions, each of which 
can contain one record. The regions are numbered in succession, beginning with 
zero. A region can be accessed by specifying its region number, and perhaps a 
key, in a data transmission statement. The key specifies the region number and 
identifies the region to allow optimized direct retrieval, replacement, addition, and 
deletion of records. 


Files 


To allow a source program to deal primarily with the logical aspects of data rather 
than with its physical organization in a data set, PL/I employs models of data sets, 
called files. These models determine how input and output statements access and 
process the associated data set. Unlike a data set, a file data item has significance 
only within the source program and does not exist as a physical entity external to 
the program. 


A name that represents a file has the FILE attribute. 


FILE attribute 


The FILE attribute specifies that the associated name is a file constant or file vari- 
able. 


The syntax for the FILE attribute is: 


r—F LL $$ _______________-_-________+< 


The FILE attribute can be implied for a file constant by any of the file description 
attributes. A name can be contextually declared as a file constant through its 
appearance in the FILE option of any input or output statement, or in an ON state- 
ment for any input/output condition. 


File constant 
Each data set processed by a PL/I program must be associated with a file constant. 


The individual characteristics of each file constant are described with file description 
attributes. These attributes fall into two categories: alternative attributes and addi- 
tive attributes. 

An alternative attribute is one that is chosen from a group of attributes. If no 
explicit or implied attribute is given for one of the alternatives in a group and if one 
of the alternatives is required, a default attribute is used. 


Figure 39 lists the PL/I alternative file attributes. 


Figure 39 (Page 1 of 2). Alternative file attributes 


Group Type Alternative Attributes Default Attribute 
Usage STREAM or RECORD STREAM 
Function INPUT or OUTPUT or UPDATE INPUT 
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Figure 39 (Page 2 of 2). Alternative file attributes 


Group Type Alternative Attributes Default Attribute 
Access SEQUENTIAL or DIRECT SEQUENTIAL 
Buffering BUFFERED or UNBUFFERED BUFFERED 


(for SEQUENTIAL files); 
UNBUFFERED (for DIRECT files) 


Scope EXTERNAL or INTERNAL EXTERNAL 


An additive attribute is one that must be stated explicitly or is implied by another 
explicitly stated attribute. The additive attributes are ENVIRONMENT, KEYED and 
PRINT. The additive attribute KEYED is implied by the DIRECT attribute. The 
additive attribute PRINT can be implied by the output file name SYSPRINT. 


Figure 40 show the attributes that apply to each type of data transmission: 


Figure 40. Attributes by data transmission type 

Type of transmission Attribute 

Stream-oriented ENVIRONMENT 
INPUT and OUTPUT 
PRINT 
STREAM 

Record-oriented BUFFERED and UNBUFFERED 
DIRECT and SEQUENTIAL 
ENVIRONMENT 
INPUT, OUTPUT, and UPDATE 
KEYED 
RECORD 


Figure 41 shows the valid combinations of file attributes. 


Figure 41 (Page 1 of 2). Attributes of PL/ file declarations 
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Figure 41 (Page 2 of oe Attributes of PL/I file declarations 
[== RECORDT,Cd 


SEQUENTIAL 
Legend: 
nee ! Must be specified 
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or implied 
D Default 
O Optional 
S Must be specified 
Organization : - Invalid 


SEQUENTIAL - FILE RECORD 
KEYED? | | FILE RECORD 
DIRECT $s SS) FILE RECORD KEYED 


Notes: 


1 A file with the INPUT attribute cannot have the PRINT attribute 
? KEYED is required for indexed and relative output 





Scope is discussed in “Scope of declarations” on page 132. 


The FILE attribute can be implied for a file constant by any of the file description 
attributes discussed in this chapter. A name can be contextually declared as a file 
constant through its appearance in the FILE option of any input or output state- 
ment, or in an ON statement for any input/output condition. 


In the following example, the name Master is declared as a file constant: 
declare Master file; 


File variable 

A file variable has the attributes FILE and VARIABLE. It cannot have any of the file 
constant description attributes. File constants can be assigned to file variables. 
After assignment, a reference to the file variable has the same significance as a 
reference tc the assigned file constant. 

The value of a file variable can be transmitted by record-oriented transmission 
statements. The value of the file variable on the data set might not be valid after 
transmission. 


The VARIABLE attribute is implied under the circumstances described in “VARI- 
ABLE attribute” on page 48. 


In the following declaration Account is declared as a file variable, and Acct1 and 
Acct2 are declared as file constants. The file constants can subsequently be 
assigned to the file variable. 


declare Account file variable, 
ACCEL Fie; 
Acc2 file; 


For syntax information, refer to “VARIABLE attribute” on page 48. 
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Specifying a file reference 
A file reference can be a file constant, a file variable, or a function reference which 
returns a value with the FILE attribute. It can be used in the following ways: 


° In a FILE or COPY option 
° As an argument to be passed to a function or subroutine 
® To qualify an input/output condition for ON, SIGNAL, and REVERT statements 
° As the expression in a RETURN statement. 
On-units can be established for a file constant through a file variable that repres- 
ents its value (see “ON-units for file variables” on page 307). In the following 
example, the statements labelled L1 and L2 both specify null ON-units for the same 
file. 
dcl F file, 

G file variable; 

G=F; 
Li: on endfile(G); 
L2: on endfile(F); 


RECORD and STREAM attributes 
The RECORD and STREAM usage attributes specify the kind of data transmission 
used for the file. 


RECORD indicates that the file consists of a collection of physically separate 
records, each of which consists of one or more data items in any form. Each 
record is transmitted as an entity to or from a variable. 


STREAM indicates that the data of the file is a continuous stream of data items, in 
character form, assigned from the stream to variables, or from expressions into the 
stream. 


The syntax for the RECORD and STREAM attributes is: 
STREAM 
>» —Lrecoro 4 


Default: STREAM. 


A file with the STREAM attribute can be specified only in the FILE option of the 
OPEN, CLOSE, GET, and PUT input/output statements. 


A file with the RECORD attribute can be specified only in the FILE option of the 
OPEN, CLOSE, READ, WRITE, REWRITE, LOCATE, and DELETE input/output 
statements. 


INPUT, OUTPUT, and UPDATE attributes 


The INPUT, OUTPUT and UPDATE function attributes specify the direction of data 
transmission allowed for a file. INPUT specifies that data is transmitted from a data 
set to the program. OUTPUT specifies that data is transmitted from the program to 
a data set, either to create a new data set or to extend an existing one. UPDATE, 
which applies to RECORD files only, specifies that the data can be transmitted in 
either direction. A declaration of UPDATE for a SEQUENTIAL file indicates the 
update-in-place mode. 
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The syntax for the INPUT, OUTPUT, and UPDATE attributes is: 


INPUT. 


QUT PUT fp =e" 
UPDATE 


Default: INPUT. 





SEQUENTIAL and DIRECT attributes 


The SEQUENTIAL and DIRECT access attributes apply only to RECORD files, and 
specify how the records in the file are accessed. 


The syntax for the SEQUENTIAL and DIRECT attributes is: 


SEQUENT IAL 
sli RECT. 4 


Abbreviation: SEQL for SEQUENTIAL 
Default: SEQUENTIAL. 


The DIRECT attribute specifies that records in a data set are directly accessed. 
The location of the record in the data set is determined by a character-string key. 
Therefore, the DIRECT attribute implies the KEYED attribute. The associated data 
set must be on a direct-access storage device. 


The SEQUENTIAL attribute specifies that records in a consecutive or relative data 

set are accessed in physical sequence, and that records in an indexed data set are 
accessed in key sequence order. For certain data set organizations, a file with the 
SEQUENTIAL attribute can also be used for direct access or for a mixture of 


random and seauantial arnrace In this naca the fila must haya thea adqitiva attri- 
1 CAFINMA veyuuws MUyvyvvuw. iw WA, PRUNAwIE Ns CANMAMILE VW OME 


bute KEYED. Existing records of a data set in a SEQUENTIAL UPDATE file can 
be modified, ignored, or, if the data set is indexed, deleted. 


BUFFERED and UNBUFFERED attributes 
The buffering attributes apply only to RECORD files. 


The syntax for the BUFFERED and UNBUFFERED attributes is: 


>> BUFFERED < 
L UNBUFFERED 


Abbreviations: BUF for BUFFERED, and UNBUF for UNBUFFERED 


Defaults: BUFFERED is the default for SEQUENTIAL files. UNBUFFERED is the 
default for DIRECT files. 


The BUFFERED attribute specifies that during transmission to and from a data set, 


each record of a RECORD file must pass through intermediate storage buffers. 
This allows both move and locate mode processing. 


234 PL/I Package/2 Language Reference 


ENVIRONMENT 


The UNBUFFERED attribute indicates that a record in a data set need not pass 
through a buffer but can be transmitted directly to and from the main storage asso- 
ciated with a variable. This allows only move mode processing. 


ENVIRONMENT attribute 
The characteristic list of the ENVIRONMENT attribute specifies various data set 
characteristics that are not part of PL/I. For a full description of the characteristics 
and their uses, refer to the PL/I Package/2 Programming Guide 


Note: Because the characteristics are not part of the PL/I language, using them in 
a file declaration can limit the portability of your application program. 


The following characteristics can be specified on the ENVIRONMENT attribute. For 
descriptions of the characteristics, refer to PL/] Package/2 Programming Guide. 


BKWD GRAPHIC RECSIZE 
CONSECUTIVE KEYLENGTH REGIONAL(1) 
CTLASA KEYLOC SCALARVARYING 
GENKEY ORGANIZATION VSAM - 


KEYED attribute 


The KEYED attribute applies only to RECORD files, and must be associated with 
indexed and relative data sets. It specifies that records in the file can be accessed 
using one of the key options (KEY, KEYTO, or KEYFROM) of record J/O state- 
ments. The syntax for the KEYED attribute is: 


p>—KEY EDA AAA > 


The KEYED attribute need not be specified unless one of the key options is used. 


PRINT attribute 
The PRINT attribute is described in “PRINT attribute” on page 270. 


Opening and closing files 


Before a file can be used for data transmission, by input or output statements, it 
must be associated with a data set. Opening a file associates the file with a data 
set and involves checking for the availability of external media, positioning the 
media, and allocating required operating system support. When processing is com- 
pleted, the file must be closed. Closing a file dissociates the file from the data set. 


PL/I provides two statements, OPEN and CLOSE, to perform these functions. 
However, use of these statements is optional. If an OPEN statement is not exe- 
cuted for a file, the file is opened implicitly during the execution of first data trans- 
mission statement for that file. In this case, the file opening uses information about 
the file as specified in a DECLARE statement (and defaults derived from the trans- 
mission statement). Similarly, if a file has not been closed before PL/I termination, 
PL/I will close it during the termination process. 


When a file for stream input, sequential input, or sequential update is opened, the 
associated data set is positioned at the first record. 
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OPEN statement 


The OPEN statement associates a file with a data set. It merges attributes speci- 
fied on the OPEN statement with those specified on the DECLARE statement. It 

also completes the specification of attributes for the file, if a complete set of attri- 

butes has not been declared for the file being opened. 


The syntax for the OPEN statement is: 


>> —OPEN—Y} options -group i-th 


options-group: 


STREAM INPUT. 
H—FILE( fi 7e-reference) 
RECORD OUTPUT. 
UPDATE 


> 
Lr ite” expression) Li INestze( expression)— 
=a 
PAGESIZE( expression) 





The options of the OPEN statement can appear in any order. 
FILE —_ specifies the name of the file that is to be associated with a data set. 


STREAM, RECORD, 
INPUT, OUTPUT, UPDATE, 
DIRECT, SEQUENTIAL, 


Pi reenaryr oene eee ae 


DUrLFEANCD, UNDUrrERED, 

KEYED, and PRINT 
options specify attributes that augment the attributes specified in the file 
declaration. The same attributes need not be listed in both OPEN and 
DECLARE statements for the same file. For a list of attributes for record 
and stream input and output, see Figure 40 on page 231. 


When a STREAM file is opened, the first GET or PUT statement can 
specify, with a statement option or format item, the first record to be 
accessed. The statement option or format item indicates that rn lines are 
skipped before a record is accessed. The file is then positioned at the 
start of the nth record. If no statement option or format item is encount- 
ered, the initial file position is the start of the first line or record. If the file 
has the PRINT attribute, it is physically positioned at column 1 of the first 
line or record 


Opening a file that is already open does not affect the file. 


TITLE The content of expression determines what is being designated. For more 
information on the TITLE attribute refer to PL/I Package/2 Programming 
Guide. 
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LINESIZE 

converted to an integer vaiue, specifies the iengih in byies of a line during 
subsequent operations on the file. New lines can be started by use of the 
printing and control format items or by options in a GET or PUT statement. 
If an attempt is made to position a file past the end of a line before explicit 
action to start a new line is taken, a new line is started, and the file is 
positioned to the start of this new line. The default line size for PRINT file 
is 120. 


The LINESIZE option can be specified only for a STREAM OUTPUT file. 
The line size taken into consideration whenever a SKIP option appears in 
a GET statement is the line size that was used to create the data set. 
Otherwise, the line size is taken as the current length of the logical record 
minus control bytes. 


PAGESIZE 
is evaluated and converted to an integer value, and specifies the number 
of lines per page. The first attempt to exceed this limit raises the 
ENDPAGE condition. During subsequent transmission to the PRINT file, a 
new page can be started by use of the PAGE format item or by the PAGE 
option in the PUT statement. The default page size is 60. 


The PAGESIZE option can be specified only for a file having the PRINT 
attribute. 


Implicit opening 
An implicit opening of a file occurs when a GET, PUT, READ, WRITE, LOCATE, 
REWRITE, or DELETE statement is executed for a file for which an OPEN state- 
ment has not already been executed. 


lf a GET statement contains a COPY option, execution of the GET statement can 
cause implicit opening of either the file specified in the COPY option or, if no file 
was specified, of the output file SYSPRINT. Implicit opening of the file specified in 
the COPY option implies the STREAM and OUTPUT attributes. 


Figure 42 shows the attributes that are implied when a given statement causes the 
file to be implicitly opened : 


Figure 42. Attributes implied by implicit open 


Statement Implied Attributes 

GET STREAM, INPUT 

PUT - STREAM, OUTPUT 

READ RECORD, INPUT(Note 1) 

WRITE RECORD, OUTPUTINote 1) 
LOCATE RECORD, OUTPUT, SEQUENTIAL 
REWRITE RECORD, UPDATE 

DELETE RECORD, UPDATE 

Note 1: 


INPUT and OUTPUT are default attributes for READ and WRITE state- 
ments only if UPDATE has not been explicitly declared. 
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When one of the statements listed in Figure 42 opens a file implicitly, it is func- 
tionally equivalent to using an explicit OPEN statement for the file with the same 
attributes specified. ; 


There must be no conflict between the attributes specified in a file declaration and 
the attributes implied as the result of opening the file. For example, the attributes 
INPUT and UPDATE are in conflict, as are the attributes UPDATE and STREAM. 


The implied attributes discussed earlier are applied before the default attrioutes 
listed in Figure 42 on page 237 are applied. Implied attributes can also cause a 
conflict. If a conflict in attributes exists after the application of default attributes, the 
UNDEFINEDFILE condition is raised. 


Figure 43. Merged and implied attributes 


Merged Attributes Implied Attributes 
UPDATE RECORD 
SEQUENTIAL RECORD 

DIRECT RECORD, KEYED 
PRINT OUTPUT, STREAM 
KEYED RECORD 


The following two examples illustrate attribute merging for an explicit opening using 
a file constant and a file variable: 


Example of file constant 


declare Listing file stream; 
open file(Listing) print; 


Attributes after merge caused by execution of the OPEN statement are STREAM 
and PRINT. Attributes after implication are STREAM, PRINT, and OUTPUT. Attri- 


i an MMONIAt 
butes after default application are STREAM, PRINT, OUTPUT, and EXTERNAL. 


Example of file variable 


declare Account file variable, 
(Acctl,Acct2) file 
output; 


Account = Acctl; 
open file(Account) print; 


Account = Acct2; 
open file(Account) record unbuf; 


The file Acct1 is opened with attributes (explicit and implied) STREAM, EXTERNAL, 
PRINT, and OUTPUT. The file Acct2 is opened with attributes RECORD, 
EXTERNAL, OUTPUT, 


Example of implicit opening 
declare Master file keyed internal; 
real file (Master) 


into (Master_Record) 
keyto(Master_Key); 
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Attributes after merge (from the implicit opening caused by execution of the READ 
statement) are KEYED, INTERNAL, RECORD, and INPUT. (No additionai aitiri- 
butes are implied.) Attributes after default application are KEYED, INTERNAL, 
RECORD, INPUT, and SEQUENTIAL. 


Examples of declarations of file constants 
declare File3 input direct environment( regional(1) ) 


This declaration specifies three file attributes: INPUT, DIRECT, and ENVIRON- 
MENT. Other implied attributes are FILE (implied by each of the attributes) and 
RECORD and KEYED (implied by DIRECT). Scope is EXTERNAL, by default. 
The ENVIRONMENT attributes specifies that the data set is of the REGIONAL(1) 
organization. 


For the previous declaration, all necessary attributes are either stated or implied in 
the DECLARE statement. None of the stated attributes can be changed (or over- 
ridden) in an OPEN statement. 


If the declaration is written as shown in the following example, invntry can be 
opened for different purposes. 


declare invntry file; 


In the following example, the file attributes are the same as those specified (or 
implied) in the DECLARE statement in the previous example. 


open file (Invntry) 
update sequential; 


The file might be opened in this way, then closed, and then later opened with a 
different set of attributes. For example, the following OPEN statement allows 
records to be read with either the KEYTO or the KEY option. 


open file (Invntry) 
input sequential keyed; 


Because the file is SEQUENTIAL, the data set can be accessed in a purely 
sequential manner. It can also be accessed directly by means of a READ state- 
ment with a KEY option. A READ statement with a KEY option for a file of this 
description obtains a specified record. Subsequent READ statements without a 
KEY option access records sequentially, beginning with the next record in KEY 
sequence. 


CLOSE statement 


The CLOSE statement dissociates an opened file from its data set. 


The syntax for the CLOSE statement is: 


sb —CLOSE—¥-FILEC ie) Ee Are een ede < 


FILE specifies the name of the file that is to be dissociated from the data set. 


The CLOSE statement also dissociates from the file all attributes established for it 
by the implicit or explicit opening process. If desired, new attributes can be speci- 
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fied for the file in a subsequent OPEN statement. However, all attributes explicitly 
given to the file constant in a DECLARE statement remain in effect. 


Closing a file that was previously closed has no effect. A closed file can be reo- 


pened. Ifa file is not closed by a CLOSE statement, it is closed at the termination 
of the program. 
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Chapter 11. Record-oriented data transmission 


This chapter describes features of the input and output statements used in record- 
oriented data transmission. Those features of PL/I that apply generally to record- 
oriented or stream-oriented data transmission, including declaring files, file 
attributes, and opening and closing files, are described in Chapter 10, “Input and 
output.” For syntax information about the ENVIRONMENT attribute refer to “ENVI- 
RONMENT attribute” on page 235. For details about environment characteristics 
and record I/O data transmission statements for each data set organization refer to 
the PL/I Package/2 Programming Guide. 


In record-oriented data transmission, data in a data set is a collection of records 
recorded in any format acceptable to the operating system. No data conversion is 
performed during record-oriented data transmission. On input, the READ statement 
either transmits a single record to a program variable exactly as it is recorded in the 
data set, or sets a pointer to the record. On output, the WRITE, REWRITE, or 
LOCATE statement transmits a single record from a program variable exactly as it 
is recorded internally. If the information transmitted to the file has a length N which 
is less than the established recora engin M, ihe resulting vaiue of tne tast M-N 
bytes of the record is undefined. 


Data transmitted 


Most variables, including parameters and DEFINED variables, can be transmitted 
by record-oriented data transmission statements. In general, the information given 
in this chapter can be applied equally to all variables. 


Note: A data aggregate must be in connected storage. If a graphic string is speci- 
fied for input or output, the SCALARVARYING option must be specified for the file. 
Other data considerations are described in the following sections. 


The following cannot be transmitted: 


* BASED, DEFINED, parameter, subscripted, or structure-base-element variables 
that are unaligned nonvarying bit strings 


* Minor structures whose first or last base elements are unaligned nonvarying bit 
strings (except where they are also the first or last elements of the containing 
major structure) 


* Major structures that have the DEFINED attribute or are parameters, and that 
have unaligned nonvarying bit strings as their first or last elements. 


VARYING strings 


242 


A locate mode output statement (see “LOCATE statement” on page 245) specifying 
a VARYING string transmits a field having a length equal to the maximum length of 
the string, plus a 2-byte prefix denoting the current length of the string. The 
SCALARVARYING option of the ENVIRONMENT attribute must be specified for the 
file. 


A move mode output statement (see “WRITE statement” on page 244 and 
“REWRITE statement” on page 244) specifying a VARYING string variable trans- 
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Area variables 


Area variables 


mits only the current length of the string. A 2-byte prefix is included only if the 
SCALARVARYING option of the ENVIRONMENT aiiribute is specified jor ihe file. 


Reading and writing using varying strings allows you to access records that may 
have undefined or unknown lengths. 


A locate mode output statement specifying an area variable transmits a field whose 
length is the declared size of the area, plus a 16-byte prefix containing control infor- 
mation. 


A move mode statement specifying an element area variable or a structure whose 
last element is an area variable transmits only the current extent of the area plus a 
16-byte prefix. 


Data transmission statements 


The data transmission statements that transmit records to or from a data set are 
READ, WRITE, LOCATE, and REWRITE. The DELETE statement deletes records 
from an UPDATE file. The attributes of the file determine which data transmission 
statements can be used. Statement options are described in “Options of data 
transmission statements” on page 245. For information about variables in data 
transmission statements, see the PL/| Package/2 Programming Guide. 


READ statement 


The READ statement can be used with any INPUT or UPDATE file. It either trans- 
mits a record from the data set to the program variable or sets a pointer to the 
record in storage. 


The syntax for the READ statement is: 


pm>—READ FILE—( f7]e-reference) 


KEY (expression) 


. KEYTO( reference 
SET( pointer-ref) 
KEY (expression) 
KEYTO( reference) 


3 $n 





The keywords can appear in any order. A READ statement without an INTO, SET, 
or IGNORE option is equivalent to a READ with an IGNORE(1). 
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WRITE 


WRITE statement 


The WRITE statement can be used with any OUTPUT file, DIRECT UPDATE file, 
or SEQUENTIAL UPDATE file. It transmits a record from the program and adds it 
to the data set. 


The syntax for the WRITE statement is: 


r>—WRITE FILE—( fi e-reference) —FROM—( reference) 
Lxev FROM expressi on) 
KEYTO( reference) 


Doma eee _______§_____» « 





The keywords can appear in any order. 


REWRITE statement 


The REWRITE statement replaces a record in an UPDATE file. For SEQUENTIAL 
UPDATE files, the REWRITE statement specifies that the last record read from the 
file is to be rewritten; consequently a record must be read before it can be 


rewritten. For DIRECT UPDATE files, any record can be rewritten whether or not it 
has first been read. 


The syntax for the REWRITE statement is: 


pe>—REWRITE FILE—( f7 le- reference) —p——— + 
FROM—( reference) 


ao. <<< 
KEY—( expression) 









The keywords can appear in any order. The FROM option must be specified for 
UPDATE files with the DIRECT attribute, or with both the SEQUENTIAL and 
UNBUFFERED attributes. 


A REWRITE statement that does not specify the FROM option has the following 
effect: 


° If the last record was read by a READ statement with the INTO option, 
REWRITE without FROM has no effect on the record in the data set. 


° If the last record was read by a READ statement with the SET option, the 
record is updated by whatever assignments were made in the variable identi- 
fied by the pointer variable in the SET option. 
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LOCATE 


LOCATE statement 


The LOCATE statement can be used only with an OUTPUT SEQUENTIAL BUF- 
FERED file for locate mode processing. It allocates storage within an output buffer 
for a based variable and sets a pointer to the location of the next record. For 
further description of locate mode processing, see “Locate mode” on page 249. 


The syntax for the LOCATE statement is: 


p> —LOCATE—based-variable—FILE—( f7/e-reference)——_—_—_§ ——cc———» 


> 3 > ¢ 
L set pointer-reference)— L eeyFROM—( expresston)— 





The keywords can appear in any order. 


based-variable 
must be an unsubscripted level-1 based variable. 


DELETE statement 


The DELETE statement deletes a record from an UPDATE file. 


The syntax for the DELETE statement is: 


p>—DELETE FILE—( f7 MEO ee ea ee a 
KEY—( expression) 


The keywords can appear in any order. If the KEY option is omitted, the record to 
be deleted is the last record that is read. No subsequent DELETE or REWRITE 
statement without a KEY is allowed until another READ statement is processed. If 
the KEY option is included, that record addressed by the key will be deleted if 
found. 


Options of data transmission statements 


FILE option 


Options that are allowed for record-oriented data transmission statements differ 
according to the attributes of the file and the characteristics of the associated data 
set. 


The FILE option must appear in every record-oriented data transmission statement. 
It specifies the file upon which the operation takes place. An example of the FILE 

option is shown in each of the statements in this section. If the file specified is not 
open in the current process, it is opened implicitly. 
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FROM 


FROM option 


IGNORE option 


The FROM option specifies the element or aggregate variable from which the 
record is written. The FROM option must be used in the WRITE statement for any 
OUTPUT or DIRECT UPDATE file. It can also be used in the REWRITE statement 
for any UPDATE file. | 


If the variable is an aggregate, it must be in connected storage. Certain uses of 
unaligned nonvarying bit strings are disallowed (for details, see “Data transmitted” 
on page 242). 


The FROM variable can be an element string variable of varying length. When 
using a WRITE statement with the FROM option, only the current length of a 
VARYING string is transmitted to a data set, and a 2-byte prefix specifying the 
length can be attached. It is attached only if the SCALARVARYING option of the 
ENVIRONMENT attribute is specified for the file. 


Records are transmitted as an integral number of bytes. If a bit string (or a struc- 
ture that starts or ends with a bit string) that is not aligned on a byte boundary is 
transmitted, the record is padded with bits at the start or the end of the string, and 
ine result Might be incorrect. 

The FROM option can be omitted from a REWRITE statement for SEQUENTIAL 
UPDATE files. If the last record was read by a READ statement with the INTO 
option, REWRITE without FROM has no effect on the record in the data set. If the 
last record was read by a READ statement with the SET option, the record 
(updated by whatever assignments were made) is copied back onto the data set. 


In the following examples, the statements specify that the value of the variable 
Mas_Rec is written into the output file Master. 


write file (Master) from (Mas_Rec); 
The REWRITE statement specifies that Mas_Rec replaces the last record read from 
an UPDATE file. 


rewrite file (Master) from (Mas_Rec); 


The IGNORE option can be used in a READ statement for any SEQUENTIAL 
INPUT or SEQUENTIAL UPDATE file. 


The expression in the IGNORE option is evaluated and converted to an integer 
value n. If nis greater than zero, n records are ignored. A subsequent READ 
statement for the file will access the (n+1)th record. If nis less than 1, the READ 
statement has no effect. 


The following example specifies that the next three records in the file are to be 
ignored: 


real file (In) ignore (3); 


246 PL/I Package/2 Language Reference 


INT 
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ption 


KEY option 


INTO 


The INTO option specifies an element or aggregate variable into which the logical 
record is read. The INTO option can be used in the READ statement for any 
INPUT or UPDATE file. 


If the variable is an aggregate, it must be in connected storage. Certain uses of 
unaligned nonvarying bit strings are disallowed (for details, see “Data transmitted” 
on page 242). 


The INTO variable can be an element string variable of varying length. If the 
SCALARVARYING option of the ENVIRONMENT attribute was specified for the file, 
each record contains a 2-byte prefix that specifies the length of the string data. 


If SCALARVARYING was not declared then, on input, the string length is calculated 
from the record length and attached as a 2-byte prefix. For VARYING bit strings, 
this calculation rounds up the length to a multiple of 8 and therefore the calculated 
length might be greater than the maximum declared length. 


The following example specifies that the next sequential record is read into the vari- 
able RECORD_1: 


read file (Detail) into (Record_l); 


The KEY option specifies a character or graphic key that identifies a record. It can 
be used in a READ statement for an INPUT or UPDATE file, or in a REWRITE 
statement for a DIRECT UPDATE file. 


The KEY option applies only to KEYED files. The KEY option is required if the file 
has the DIRECT attribute and optional if the file has the SEQUENTIAL and KEYED 
attributes. 


The expression in the KEY option is evaluated and, if not character or graphic, is 
converted to a character value that represents a key. It is this character or graphic 
value that determines which record is read. 


The following example specifies that the record identified by the character value of 
the variable Stkey is read into the variable Item: 


read file (Stpck) into (Item) key (Stkey); 


KEYFROM option 


The KEYFROM option specifies a character or graphic key that identifies the record 
on the data set to which the record is transmitted. It can be used in a WRITE 
statement for any KEYED OUTPUT or DIRECT UPDATE file, or in a LOCATE 
statement. 


The KEYFROM option applies only to KEYED files. The expression is evaluated 
and, if not character or graphic, is converted to a character string and is used as 
the key of the record when it is written. 


Relative data sets can be created using the KEYFROM option. The record number 
is specified as the key. 
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KEYTO 


KEYTO option 


SET option 


REGIONAL(1) data sets can be created using the KEYFROM option. The region 
number is specified as the key. 


For indexed data sets, KEYFROM specifies a recorded key whose length must be 
equal to the key length specified for the data set. 


The following example specifies that the value of Loanrec is written as a record in 
the file Loans, and that the character string value of Loanno is used as the key with 
which it can be retrieved: 


write file (Loans) from (Loanrec) keyfrom (Loanno); 


The KEYTO option specifies the character or graphic variable to which the key of a 
record is assigned. The KEYTO option can specify any string pseudovariable other 
than STRING. It cannot specify a variable declared with a numeric picture specifi- 
cation. The KEYTO option can be used in a READ statement for a SEQUENTIAL 
INPUT or SEQUENTIAL UPDATE file. 


The KEYTO option applies only to KEYED files. 


Assignment to the KEYTO variable always follows assignment to the INTO variable. 
If an incorrect key specification is detected, the KEY condition is raised. The value 
assigned is as follows: 


* For indexed data sets, the record key is padded or truncated on the right to the 
declared length of the character variable. 


* For relative data sets, a record number is converted to a character string with 
leading zeros suppressed, truncated, or padded on the left to the declared 
length of the character variable. 


* For REGIONAL(1) data sets, the 9-character region-number, padded or trun- 
cated on the left to the declared length of the character variable. If the char- 
acter variable is of varying length, any leading zeros in the region number are 
truncated and the string length is set to the number of significant digits. An 
all-zero region number is truncated to a single zero. 


The KEY condition is not raised for this type of padding or truncation. 


The following example specifies that the next record in the file Detail is read into 
the variable Invntry, and that the key of the record is assigned to the variable 
Keyf ld: 


read file (Detail) into (Invntry) keyto (Keyfld); 


The SET option can be used with a READ statement or a LOCATE statement. For 
the READ statement, it specifies a pointer variable that is set to point to the record 
read. For the LOCATE statement, it specifies a pointer variable that is set to point 
to the next record for output. 


If the SET option is omitted for the LOCATE statement, the pointer declared with 
the record variable is set. If a VARYING string is transmitted, the 
SCALARVARYING option must be specified for the file. 
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Processing modes 


The following example specifies that the value of the pointer variable P is set to the 
iocation in ihe buffer of ine next sequeniial record: 
read file (X) set (P); 


Processing modes 


Move mode 


Locate mode 


Record-oriented data transmission has two modes of handling data: 
Move mode processes data by moving it into or out of the variable. 


Locate mode _ processes data while it remains in a buffer. The execution of a 
data transmission statement assigns a pointer variable for the 
location of the storage allocated to a record in the buffer. Locate 
mode is applicable only to BUFFERED files. 


The data transmission statements and options that you specify determine the proc- 
essing mode used. 


In move mode, a READ statement transfers a record from the data set to the vari- 
able named in the INTO option. A WRITE or REWRITE statement transfers a 
record from the variable named in the FROM option to the data set. The variables 
named in the INTO and FROM options can be of any storage class. 


The following is an example of move mode input: 
Eof_In = 'O'b; 

on endfile(In) Eof_In = '1'B; 

read file(In) into(Data); 

do while (-Eof_In); 


/* process record */ 
read file(In) into(Data); 
end; 


Locate mode assigns to a pointer variable the location of the buffer. A based vari- 
able described the record. The same data can be interpreted in different ways by 
using different based variables. Locate mode can also be used to read self- 
defining records, in which information in one part of the record is used to indicate 
the structure of the rest of the record. For example, this information could be an 
array bound or a code identifying which based structure should be used for the 
attributes of the data. 


A READ statement with a SET option sets the pointer variable in the SET option to 
a buffer containing the record. The data in the record can then be referenced by a 
based variable qualified with the pointer variable. 


The pointer value is valid only until the execution of the next READ or CLOSE 
statement that refers to the same file. 
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The pointer variable specified in the SET option or, if SET was omitted, the pointer 
variable specified in the declaration of the based variable, is used. The pointer 
value is valid only until the execution of the next LOCATE, WRITE, or CLOSE 
statement that refers to the same file. It also initializes components of the based 
variable that have been specified in REFER options. 


The LOCATE statement sets a pointer variable to a large enough area where the 
next record can be built. 


After execution of the LOCATE statement, values can be assigned directly into the 
based variables qualified by the pointer variable set by the LOCATE statement. 


The following example shows locate mode input: 


dcl 1 Data based(P), 
2 


on endfile(In) 


read file(in) set(P); 
do while (7endfile(In)); 
/* process record */ 
read file(In) set(P); 
end; 


The following example shows locate mode output: 


dcl 1 Data based(P); 
2 


do while (More_records_to_write); 


b ipeaeess a 
| 
. 


/* build record */ 
end; 


250 =~ PL/I Package/2 Language Reference 





Chapter 12. Stream-oriented data transmission 


Chapter 12. Stream-oriented data transmission ............... 252 
Data transmission statements ..........0..0. 0.0.00 ee eee ees 252 
GET statement ..... bsSeetht Bh je cierad fh ornate: hel eae et Sr oe ae erst dokp Shake 8 253 
PUT SIAtEMeDE :s2: BS oie oe CU eae a8 beh ee ee ee ks 253 
Options of data transmission statements ..................... 254 
GOPNODUOM: 2.6 pecs ag Ge Sa ee Ho ee Ghee ds Set Bee a 254 
Data specification options ............. 2.0.00 0002. eee 254 
Pil ODUON 3.0. 4s a BA hs Bd ee Peeks Ay BS ae Mee ele ee 256 
LINESODUON: x 6 -io- 5.1.x 8 ale. a Gs Be bs he A eS BT es ee I BAM ees 256 
PAGE ODUOM: 2sfancl de aminaace aterainn ae pk ee a Gea gee ae ee a ee ets 256 
SISIPODUOM, 415 3 tw katate wee Ae ie Fe ae 257 
SO EUINGYODHOM: | x a2 fen dcatod: ey tava Sas ail we Be oa pee laton gh Sdn weer NP Sete AS 257 
Transmission of data-list items ...........0....0.. 0.2.0 2200. 259 
Data-directed data specification ................. 0.2.0.0. 00. 259 
Syntax of data-directed data... .... 2... ee 260 
GET data-dwtecled) (a ures ao Oe aoe ee Fe a aay er etree a 261 
PUT Gala-divected:. «es. sate 3 aoe ee ulated a Pe bee e Rae ees SY 262 
Edit-directed data specification .................. 2.0... 00.2., 263 
GET edi-directed:. 3.4. sla Golan hate eee We ae, BAL ae ts Bale YB 265 
PUT Sdil-direCted:: - a 0s-ee bBo. 8 WS Cat 4 ee woes. oes B be 266 
FORMAT statement ..........02... 00.0.0 02.00 2 es 267 
List-directed data specification .................. 00... .004. 267 
Syntax of list-directed data .........22.20002.0. 2.00.20 0204. 268 
GET list-directed ©... 2.0.00 .000 000 .0.000.. hone ante ants & 268 
PUT ASECIECIED nti/s Katee ear eee ae he De eS bh a oot 269 
PRINT -attiribute: %.5..2 ate ne wk & bem Soa tes Here Bok DOR eR eS oY 270 
DBCS datainstreaamVVO .. 2... 272 


© Copyright IBM Corp. 1992 251 


Stream-oriented data transmission 





Chapter 12. Stream-oriented data transmission 


This chapter describes the input and output statements used in stream-oriented 
data transmission. Features that apply to stream-oriented and record-oriented data 
transmission, including files, file attributes, and opening and closing files, are 
described in Chapter 10, “Input and output” on page 228. 


Stream-oriented data transmission treats a data set as a continuous stream of data 
values in character, graphic, or mixed character data form. Within a program, 
record boundaries are generally ignored. However, a data set consists of a series 
of lines of data, and each data set created or accessed by stream-oriented data 
transmission has a line size associated with it. In general, a line is equivalent to a 
record in the data set, but the line size does not necessarily equal the record size. 


The stream-oriented data transmission statements can also be used for internal 
data movement, by specifying the STRING option instead of specifying the FILE 
option. Although the STRING option is not an input/output operation, its use is 

described in this chapter. 


Stream-oriented data transmission can be list-directed, data-directed, or edit- 
directed. 


List-directed data transmission 
transmits the values of data-list items without your having to specify the 
format of the values in the stream. The values are recorded externally as 
a list of constants, separated by blanks or commas. 


Data-directed data transmission 
transmits the names of the data-list items, as well as their values, without. 
your having to specify the format of the values in the stream. The 
GRAPHIC option of the ENVIRONMENT attribute must be specified if any 
variable has a DBCS name, even if no DBCS data is present. 


H ali taal elas barre ees 
Edit-directed data transmission 


transmits the values of data-list items and requires that you specify the 
format of the values in the stream. The values are recorded externally as 
a string of characters or graphics to be treated character by character (or 
graphic by graphic) according to a format list. 


The following sections detail the data transmission statements and their options, 
and how to specify the list-, data-, and edit-directed data. How to accommodate 
double-byte characters is discussed in “DBCS data in stream I/O” on page 272. 


Data transmission statements 


252 


Stream-oriented data transmission uses GET and PUT statements. Only consec- 
utive files can be processed with the GET and PUT statements. 


The variables or pseudovariables to which data values are assigned, and the 
expressions from which they are transmitted, are generally specified in a data- 
specification with each GET or PUT statement. The statements can also include 
options that specify the origin or destination of the data values or indicate where 
they appear in the stream relative to the preceding data values. Options for the 
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GET 


stream-data transmission statements are described in “Options of data transmission 
statements” on page 254. 


GET statement 


The GET statement is a STREAM input data transmission statement that can 
either: 


* Assign data values from a data set to one or more variables 
* Assign data values from a string to one or more variables. 


The syntax of the GET statement for a stream input file is: 


eee) Laser 
FILE—( expression) data-specificatio 


> ;—— ¢ 
COPY SKIP 
(fi le-reference) (expression) 





The keywords can appear in any order. The data specification must appear unless 
the SKIP option is specified. 


The syntax of the GET statement for transmission from a string is: 


>>—GET STRING—( expression)—data-speci fication—;———___-_---___ >» « 


If FILE or STRING option is not specified FILE(SYSIN) is assumed and SYSIN is 
implicitly declared FILE STREAM INPUT EXTERNAL. 


PUT statement 


The PUT statement is a STREAM output data transmission statement that can: 


* Transmit values to a stream output file 
* Assign values to a character variable. 


The syntax of the PUT statement for a stream output file is: 


oy Wane ete ee = 
FILE—( fiJe-reference) data-specificatio 


3 


LINE—( expression) 


LINE—( expression) 





The keywords can appear in any order. The data specification can be omitted only 
if one of the control options (PAGE, SKIP, or LINE) appears. 


The syntax of the PUT statement for transmission to a character string is: 


p>—PUT STRING—( expression)—data-speci fication—;———_—__—___-- 
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Options of data transmission statements 


COPY option 


The COPY option specifies that the source data stream will be written on the speci- 
fied STREAM OUTPUT file without alteration. If no file reference is given, the 
default is the output file SYSPRINT. Each new record in the input stream starts a 
new record on the COPY file. For example: 


get file(sysin) data(A,B,C) copy(DPL); 


not only transmits the values assigned to A, B, and C in the input stream to the 
variables with these names, but also writes them exactly as they appear in the 
input stream, on the file DPL. Data values that are skipped on input, and not trans- 
mitted to internal variables, copy intact into the output stream. 


If a condition is raised during the execution of a GET statement with a COPY 
option and an ON-unit is entered in which another GET statement is executed for 
the same file, and if control is returned from the ON-unit to the first GET statement, 
that statement executes as if no COPY option was specified. If, in the ON-unit, a 


PUT statement is executed for the file associated with the COPY option, the posi- 


tion of the data transmitted might not immediately follow the most recently- 
transmitted COPY data item. 


If the COPY option file is not open in the current program, the file is implicitly 
opened in the program for stream output transmission. 


Data specification options 


Data specifications in GET and PUT statements specify the data to be transmitted. 
The syntax for a data specification is: 


>> (4 data-list -) < 
| Li tst | 
me See aie 


EDIT—*(4 data-list |-)—( format-list 
data-list: 





Naar 






wifes” ite 
(Sdata-list-item_type-3-00) 





If a GET or PUT statement includes a data list that is not preceded by one of the 
keywords LIST, DATA, or EDIT, LIST is the default. 


Important: In a statement without LIST, DATA, or EDIT preceding the data list, 
the data list must immediately follow the GET or PUT keyword. Any options 
required must be specified after the data list. 


DATA Refer to “Data-directed data specification” on page 259. 
EDIT Refer to “Edit-directed data specification” on page 263. 
LIST Refer to “List-directed data specification” on page 267. 
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Data specification 


data-list item 
On inpui, a daia-list item for edii-directed and lisi-directed ivansmission 
can be one of the following: an element, array, or structure variable. For 
a data-directed data specification, a data-list item can be an element, 
array, or structure variable. None of the names in a data-directed data list 
can be subscripted or locator-qualified. However, qualified (that is, 
structure-member) or string-overlay-defined names are allowed. 


On output, a data list item for edit-directed and list-directed data specifica- 
tions can be an element expression, an array expression or a structure 
expression. For a data-directed data specification, a data-list item can be 
an element, array, or structure variable. It must not be locator-qualified. It 
can be qualified (that is, a member of a structure) or string-overlay- 
defined. 


The data types of a data-list item can be any computational data. In this 
case, the name of the variable is transmitted, but not its value. 


An array or structure variable in a data-list is equivalent to n items in the 
data list, where nis the number of element items in the array or structure. 
For edit-directed transmission, each element item is associated with a sep- 
arate use of a data-format item. 


data-list item type-3-DO 
The syntax for the Type 3 DO specification is described under “DO 
statement” on page 173. Data list items with Type 3 DO specifications 
are not permitted in data-directed data lists. 


When the last repetitive specification is completed, processing continues 
with the next data-list item. 


Each repetitive specification must be enclosed in parentheses, as shown 
in the syntax diagram. If a data specification contains only a repetitive 
specification, two sets of outer parentheses are required, since the data 
list is enclosed in parentheses and the repetitive specification must have a 
separate set. . 


When repetitive specifications are nested, the rightmost DO is at the outer 
level of nesting. For example: 
get list (((ACI,J) 


do I = 1 to 2) 
do J = 3 to 4)); 


There are three sets of parentheses, in addition to the set used to delimit 
the subscripts. The outermost set is the set required by the data specifi- 
cation. The next set is that required by the outer repetitive specification. 

The third set of parentheses is required by the inner repetitive specifica- 

tion. 


This statement is equivalent in function to the following nested do-groups: 


do J = 3 to 4; 
do I = 1 to 2; 
get list (A (I,uJ)); 
end; 
end; 


It assigns values to the elements of the array A in the following order: 
A(1,3), A(2,3), A(1,4), A(2,4) 
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FILE 


FILE option 


LINE option 


PAGE option 


format list 
For a description of the format list, see “Edit-directed data specification” on 
page 263. 


The FILE option specifies the file upon which the operation takes place. It must be 
a STREAM file. For information on how to declare a file type data item, see “Files” 
on page 230. 


If neither the FILE option nor the STRING option appears in a GET statement, the 
input file SYSIN is the default; if neither option appears in a PUT statement, the 
output file SYSPRINT is the default. 


The LINE option can be specified only for PRINT files. The LINE option defines a 
new current line for the data set. The expression is evaluated and converted to an 
integer value, n. The new current line is the nth line of the current page. If at least 
n lines have already been written on the current page or if n exceeds the limits set 
by the PAGESIZE option of the OPEN statement, the ENDPAGE condition is 
raised. If nis less than or equal to zero, a value of 1 is used. If n specifies the 
current line, ENDPAGE is raised except when the file is positioned on column 1, in 
which case the effect is the same as if a SKIP(O) option were specified. 


The LINE option takes effect before the transmission of any values defined by the 
data specification (if any). If both the PAGE option and the LINE option appear in 
the same statement, the PAGE option is applied first. For example: 


put file(List) data(P,Q,R) line(34) page; 


prints the values of the variables P, Q, and R in data-directed format on a new 
page, commencing at line 34. 


For the effect of the LINE option when specified in the first GET statement following 
the opening of the file, see “OPEN statement” on page 236. 


For output to a terminal in interactive mode, the LINE option skips three lines. 


The PAGE option can be specified only for PRINT files. It defines a new current 
page within the data set. If PAGE and LINE appear in the same PUT statement, 
the PAGE option is applied first. The PAGE option takes effect before the trans- 
mission of any values defined by the data specification (if any). 


The page remains current until the execution of a PUT statement with the PAGE 
option, until a PAGE format item is encountered, or until the ENDPAGE condition is 
raised, resulting in the definition of a new page. A new current page implies line 
one. 


For output to a terminal in interactive mode, the PAGE option skips three lines. 
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SKIP option 


STRING option 


SKIP 


The SKIP option specifies a new current line (or record) within the data set. The 
expression is evaluated and converted to an integer value, n. The data set is posi- 
tioned to the start of the nth line (record) relative to the current line (record). If 
expression is not specified, the default is SKIP(1). 


The SKIP option takes effect before the transmission of values defined by the data 
specification (if any). For example: 


put list(X,Y,Z) skip(3); 


prints the values of the variables X, Y, and Z on the output file SYSPRINT com- 
mencing on the third line after the current line. 


For non-PRINT files and input files, if the expression in the SKIP option is less than 
or equal to zero, a value of 1 is used. For PRINT files, if n is less than or equal to 
zero, the positioning is to the start of the current line. 


For the effect of the SKIP option when specified in the first GET statement following 
the opening of the file, see “OPEN statement” on page 236. 


If fewer than n lines remain on the current page when a SKIP(n) is issued, 
ENDPAGE is raised. 


When printing at a terminal in conversational mode, SKIP(n) with n greater than 3 
is equivalent to SKIP(3). No more than three lines can be skipped. 


The STRING option in GET and PUT statements transmits data between main 
storage locations rather than between the main and a data set. DBCS data items 
cannot be used with the STRING option. 


The GET statement with the STRING option specifies that data values assigned to 
the data list items are obtained from the expression, after conversion to character 
string. Each GET operation using this option always begins at the leftmost char- 
acter position of the string. If the number of characters in this string is less than 
the total number of characters specified by the data specification, the ERROR con- 
dition is raised. 


The PUT statement with the STRING option specifies that values of the data-list 
items are to be assigned to the specified character variable or pseudovariable. The 
PUT operation begins assigning values at the leftmost character position of the 
string, after appropriate conversions are performed. Blanks and delimiters are 
inserted as in normal I/O operations. If the string is not long enough to accommo- 
date the data, the ERROR condition is raised. 


The NAME condition is not raised for a GET DATA statement with the STRING 
option. Instead, the ERROR condition is raised for situations that raise the NAME 
condition for a GET DATA statement with the FILE option. 

The following restrictions apply to the STRING option: 


°* The COLUMN control format option cannot be used with the STRING option. 
°® No pseudovariables are allowed in the STRING option of a PUT statement. 
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STRING 


The STRING option is most useful with edit-directed transmission. It allows data 
gathering or scattering operations performed with a single statement, and it allows 
stream-oriented processing of character strings that are transmitted by record- 
oriented statements. 


For example: 
read file (Inputr) into (Temp); 
get string(Temp) edit (Code) (F(1)); 
If Code = 1 then © 
get string (Temp) Edit (X,Y,Z) 
(X(1), 3 F(10,4)); 


The READ statement reads a record from the input file Inputr. The first GET 
statement uses the STRING option to extract the code from the first byte of the 
record and assigns it to Code. If the code is 1, the second GET statement uses the 
STRING option to assign the values in the record to X, Y, and Z The second GET 
statement specifies that the first character in the string Temp is ignored (the X(1) 
format item in the format list). This ignored character is the same one assigned to 
Code by the first GET statement. 


rr 


put string (Record) edit 
(Name ) (X(1), A(12)) 
( Pay#) (X(10), A(7)) 
(Hours*Rate) (X(10), P'$999V.99'); 


write file (Qutprt) from (Record); 


The PUT statement specifies, by the X(1) spacing format item, that the first char- 
acter assigned to the character variable is to be a single blank, which is the ANS 
vertical carriage positioning character that specifies a single space before printing. 
Following that, the values of the variables Name and Pay# and of the expression 
Hours*Rate are assigned. The WRITE statement specifies that record transmission 
is used to write the record into the file Outprt. 


The variable referenced in the STRING option should not be referenced by name or 
by alias in the data list. For example: 


declare S char(8) init('YYMMDD'); 
put string (S) edit 
CSUDSEM CSs. Se Zp. hy 
SURS ETS a ks ey 
substr (S, 1; 2)) 
(A); 


The value of S after the PUT statement is 'MM/ib/MM' and not 'MM/DD/YY' 
because S is blanked after the first data item is transmitted. The same effect is 
obtained if the data list contains a variable based or defined on the variable speci- 
fied in the STRING option. 
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Transmission of data-list items 


Transmission of data-list items 


If a data-list item is of complex mode, the real part is transmitted before the imagi- 
nary part. 


If a data-list item is an array expression, the elements of the array are transmitted 
in row-major order; that is, with the rightmost subscript of the array varying most 
frequently. 


If a data-list item is a structure expression, the elements of the structure are trans- 
mitted in the order specified in the structure declaration. 


For example, the statements 


declare 1 A (10), 
2B; 
eC; 
put file(X) list(A); 
result in the output being ordered as follows: 


A.B(1) A.C(1) A.B(2) A.C(2) A.B(3) 
ROO 


If, however, the declaration is: 


declare 1 A, 
2 B(10), 
CULO): 


the same PUT statement results in the output ordered as follows: 


A.B(1) A.B(2) A.B(3) ... A.B(10) 
ALCL) ACOZ) ALCO) nae ALCO1O) 


If an input statement for list- or edit-directed transmission assigns a value to a vari- 
able in a data list, the assigned value is used if the variable appears in a later 
reference in the data list. For example: 


get list (N,(X(I) do I=] to N),J,K,); 
substr (Name, J,K)); 


When this statement is executed, values are transmitted and assigned in the fol- 
lowing order: 
1. Anew value is assigned to N. 


2. Elements are assigned to the array X as specified in the repetitive specification 
in the order X(1),X(2),...X(N), with the new value of N specifying the number 
of assigned items. 


3. A new value is assigned to J. 


4. A new value Is assigned to K 


Data-directed data specification 


For a description of the syntax of the DATA data specification, refer to “Data spec- 
ification options” on page 254. 


Names of structure elements in the data-list item need only have enough quailifica- 
tion to resolve any ambiguity. Full qualification is not required. 
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Syntax of data-directed data 


Omission of the data list results in a default data list that contains all computational 
variables that could be named in a data-directed statement. 


On output, all items in the data list are transmitted. If two or more blocks con- 
taining the PUT statement each have declarations of items that have the same 
name, all the items are transmitted. The item in the innermost block appears first. 
Parameters, based variables, defined variables, and subscripted variables are not 
permitted in data-directed lists. 


Syntax of data-directed data 


The stream associated with data-directed data transmission is in the form of a list 
of element assignments. The element assignments that have optionally signed 
constants, like variable names and equal signs, are in character or graphic form. 
The syntax for the element assignments is: 





—h 
le es = —data-valu re | 


On input, the element assignments can be separated by either a blank or a comma. 
Blanks can surround periods in qualified names, subscripts, subscript parentheses, 
and the assignment symbols. On output, the assignments are separated by a 
blank. For PRINT files, items are separated according to program tab settings. 


Each data-value in the stream has one of the syntaxes described for list-directed 
transmission. For a description of list-directed transmission syntax, refer to “Syntax 
of list-directed data” on page 268. 


The length of the data value in the stream is a function of the attributes declared for 
the variable and, because the name is also included, the length of the fully qualified 
subscripted name. The length for output items converted from coded arithmetic 
data, numeric character data, and bit-string data is the same as that for list-directed 
output data, and is governed by the rules for data conversion to character type as 
described in Chapter 5, “Data conversion.” 


Qualified names in the input stream must be fully qualified. 


Interleaved subscripts cannot appear in qualified names in the stream. For 
example, assume that Y is declared as follows: 


declare 1 Y(5,5), 
2 A(10), 
3B, 


ay 
aris 


An element name has to appear in the stream as follows: 
VsAsBU 2,358)" 6.72 
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GET data-directed 


GET data-directed 


For more information about the GET statement, see “GET statement” on page 253. 


If a data list is used, each data-list item must be an element, array, or structure 
variable. Names cannot be subscripted, but qualified names are allowed in the 
data list. All names in the stream should appear in the data list; however, the order 
of the names need not be the same, and the data list can include names that do 
not appear in the stream. 


If the data list contains a name that is not included in the stream, the value of the 
named variable remains unchanged. 


If the stream contains an unrecognizable element-variable or a name that does not 
have a counterpart in the data list, the NAME condition is raised. 


Transmission ends when a semicolon that is not enclosed in quotation marks or an 
end-of-file is reached. The recognition of the semicolon or end-of-file determines 
the number of element assignments that are actually transmitted by a particular 
statement, whether or not a data list is specified. 


For example, consider the following data list, where A, B, C, and D are names of 
element variables: 


Data (B, A, C, D) 


This data list can be associated with the following input data stream: 
A= 2.5, B= .0047, D= 125, Z= ‘ABC’; 


Because C appears in the data list but not in the stream, its value remains unal- 
tered. Z, which is not in the data list, raises the NAME condition. 


If the data list includes the name of an array, subscripted references to that array 
can appear in the stream although subscripted names cannot appear in the data 
list. The entire array need not appear in the stream; only those elements that actu- 
ally appear in the stream will be assigned. If a subscript is out of range, or is 
missing, the NAME condition is raised. 


For example: 
declare X (2,3); 


Consider the following data list and input data stream: 
Data Specification Input Data Stream 
data (X) AGT 1.95, 
X(1,2)= 8085, 
KCL o> 735 
Although the data list has only the name of the array, the input stream can contain 


values for individual elements of the array. In this case, only three elements are 
assigned; the remainder of the array is unchanged. 
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PUT data-directed 


If the data list includes the names of structures, minor structures, or structure ele- 
ments, fully qualified names must appear in the stream, although full qualification is 
not required in the data list. For example: 
dey.) bits 
2 Partno, 
2 Descrp, 
2 Price, - 
3 Retail, 
3 Whsl; 


If it is desired to read a value for In.Price.Retail, the input data stream must have 


‘the following form: 


In. Price. Retail=1.23; 


The data specification can be any of: 


data(In) 

data( Price) 
data(In.Price) 
data( Retail) 
data(Price.Retail) 
data( in. Retail) 


data(In.Price.Retail) 


PUT data-directed 


For more information about the PUT statement, see “PUT statement” on page 253. 


A data-list item can be an element, array, or structure variable, or a repetitive spec- 
ification. Subscripted names are not allowed. The names appearing in the data 
list, together with their values, are transmitted in the form of a list of element 
assignments separated by blanks and terminated by a semicolon. For PRINT files, 
items are separated according to program tab settings; see “PRINT attribute” on 
page 270. 


ee ee Shh Se — 2 


A semicoion is written into tne stream afier tne iast 
PUT statement. 


aia item transmitted by eacn 


Names are transmitted as all SBCS or all DBCS, regardless of how they are speci- 
fied in the data list. If a name contains only SBCS characters, it is transmitted as 
all SBCS; otherwise, it is transmitted as DBCS. Each name in a qualified reference 
is handled independently. For example: 


put data (.A.B.C.Skk); 
would be transmitted as: 
ABCSkk=value-of-variable 


Note: In the previous example, .A.B.C.Skk is a scalar variable. 


Data-directed output is not valid for subsequent data-directed input when the 
character-string value of a numeric character variable does not represent a valid 
optionally signed arithmetic constant, or a complex expression. 


For character data, the contents of the character string are written out enclosed in 
quotation marks. Each quotation mark contained within the character string is 
represented by two successive quotation marks. 


262 PL/I Package/2 Language Reference 


Edit-directed data specification 


The following example shows data-directed transmission (both input and output): 


declare (A(6), B(7)) fixed; 
get file (X) data (B); 
do I =1to6: 

ACL) ='B €141)-*°B CD): 
end; 
put file (Y) data (A); 


input stream: 
BULJ=1, BC2)=2.. BCS) 
B(4)=1, B(5)=2, B(6) 
output stream: 


A(1)= 3 A(2)= 5 A(3)= 4 A(4)= 3 
ACS)=-5 ACO)= 7% 


3, 
35. BCI )=45 


ol 


In the following example: 


dcl 1A, 
2 B FIXED, 
ag Oo 
3 D FIXED; 
A.B = 2; 
Alt 


put data (A); 


the data fields in the output stream are as follows: 
A.B= 2 A.C.D= 17; 


Edit-directed data specification 


For information on the syntax of the EDIT data specification, refer to “Data specifi- 
cation options” on page 254. 


The syntax for an edit-directed format list specification is: 


>> format-7te < 
n—format-ite 
n—( format-list) 





n specifies an iteration factor, which is either an expression enclosed in 
parentheses or an integer. If it is the latter, a blank must separate the 
integer and the following format item. 


The iteration factor specifies that the associated format item or format list 
is used n successive times. A zero or negative iteration factor specifies 
that the associated format item or format list is skipped and not used (the 
data-list item is associated with the next data-format item). 


If an expression is used to represent the iteration factor, it is evaluated 
and converted to an integer, once for each set of iterations. 


The associated format item or format list is that item or list of items imme- 
diately to the right of the iteration factor. 
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Edit-directed data specification 


format item 
specifies either a data-format item, a control-format item, or the remote 
format item. Syntax and detailed discussions of the format items appear 
in Chapter 13, “Edit-directed format items.” 


Data-format items 
describe the character or graphic representation of a single data item. 
They are: 


character 

bit 

complex 
floating point 
fixed point 
graphic 
picture 


VOTmmMOD > 


Control-format items 
specify the layout of the data set associated with a file. They are: 


COLUMN 
LINE 
PAGE 
SKIP 

X 


The remote-format item 
specifies a label reference whose value is the label constant of a FORMAT 
statement located elsewhere. The FORMAT statement contains the 
remotely situated format items. The label reference item is: 


R(label-reference) 
where label is the label constant name of the FORMAT statement. 
For information on specifying the R-format item, see “R-format item” 
on page 282. 


The first data-format item is associated with the first data-list item, the second data- 
format item with the second data-list item, and so on. If a format list contains fewer 
data-format items than there are items in the associated data list, the format list is 
reused. If there are excessive format items, they are ignored. 


Suppose a format list contains five data-format items and its associated data list 
specifies ten items to be transmitted. The sixth item in the data list is associated 
with the first data-format item, and so forth. Suppose a format list contains ten 
data-format items and its associated data list specifies only five items. The sixth 
through the tenth format items are ignored. 


lf a control-format item is encountered, the control action is executed. 


The PAGE and LINE control-format items can be used only with PRINT files and, 
consequently, can appear only in PUT statements. The SKIP, COLUMN, and 
X-format items apply to both input and output. 


The PAGE, SKIP, and LINE format items have the same effect as the corre- 
sponding options of the PUT statement (and of the GET statement, in the case of 
SKIP), except that the format items take effect when they are encountered in the 
format list, while the options take effect before any data is transmitted. 
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GET edit-directed 


The COLUMN format item cannot be used in a GET STRING or PUT STRING 
siaiemeni. 


For the effects of control-format items when specified in the first GET or PUT state- 
ment following the opening of a file, see “OPEN statement” on page 236. 


A value read into a variable can be used in a format item that is associated with 
another variable later in the data list. 


get edit (M,String_A,I,String_B)(F(2),AC(M),X(M),F(2),A(T)); 


In this example, the first two characters are assigned to M The value of M specifies 
the number of characters assigned to String_A and the number of characters being 
ignored before two characters are assigned to I, whose value is used to specify the 
number of characters assigned to String_B. 


The value assigned to a variable during an input operation can be used in an 
expression in a format item that is associated with a later data item. An expression 
in a format item is evaluated and converted to an integer each time the format item 
is used. 


The transmission is complete when the last data-list item has been processed. 
Subsequent format items, including control-format items, are ignored. 


GET edit-directed 


For more information about the GET statement, see “GET statement” on page 253. 


Data in the stream is a continuous string of characters and graphics with no delim- 
iters between successive values. The number of characters for each data value is 
specified by a format item in the format list. The characters are interpreted 
according to the associated format item. When the data list has been processed, 
execution of the GET statement stops and any remaining format items are not proc- 
essed. 


Each data-format item specifies the number of characters or graphics to be associ- 
ated with the data-list item and how to interpret the data value. The data value is 
assigned to the associated data-list item, with any necessary conversion. 


Fixed-point binary and floating-point binary data values must always be represented 
in the input stream with their values expressed in decimal digits. The F-, P-, and 
E-format items can then be used to access them, and the values are converted to 
binary representation upon assignment. 


All blanks and quotation marks are treated as characters in the stream. Strings 
should not be enclosed in quotation marks. Quotation marks should not be 
doubled. The letter B should not be used to identify bit strings or G to identify 
graphic strings. If characters in the stream cannot be interpreted in the manner 
specified, the CONVERSION condition is raised. 


Example: 
get edit (Name, Data, Salary)(A(N), X(2), A(6), F(6,2)); 
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PUT edit-directed 


This example specifies the following: 


° The first N characters in the stream are treated as a character string and ~ 
assigned to Name. 


°* The next two characters are skipped. 
* The next six characters are assigned to Data in character format. 


°* The next six characters are considered an optionally signed decimal fixed-point 
constant and assigned to Salary. 


PUT edit-directed 


For more information about the PUT statement, see “PUT statement” on page 253. 


The value of each data-list item is converted to the character or graphic represen- 
tation specified by the associated data-format item and placed in the stream in a 
field whose width also is specified by the format item. When the data list has been 
processed, execution of the PUT statement stops and any remaining format items 
are not processed. 


er Tove Ae 


E-format items must state the field width and point placement in terms of the con- 
verted decimal number. For the P-format these are specified by the picture specifi- 
cation. 


On output, binary items are converted to decimal values and the associated F- or 


On output, blanks are not inserted to separate data values in the output stream. 
String data is left-adjusted in the field to the width specified. Arithmetic data is 
right-adjusted. Because of the rules for conversion of arithmetic data to character 
type which can cause up to 3 leading blanks to be inserted (in addition to any 
blanks that replace leading zeros), generally there is at least 1 blank preceding an 
arithmetic item in the converted field. Leading blanks do not appear in the stream, 
however, unless the specified field width allows for them. Truncation, due to inade- 
quate field-width specification, is on the left for arithmetic items, and on the right for 
string items. SIZE or STRINGSIZE is raised if truncation occurs. 


Example 1 
put edit('Inventory='|Inum, Invcode)(A,F(5)); 


This example specifies that the character string 'Inventory=' is concatenated with 
the value of Inum and placed in the stream in a field whose width is the length of 
the resultant string. Then the value of Invcode is converted to character, as 
described by the F-format item, and placed in the stream right-adjusted in a field 
with a width of five characters (leading characters can be blanks). 


Example 2: The following example shows the use of the COLUMN, LINE, PAGE, 
and SKIP format items in combination with one another: 


put edit (‘Quarterly Statement’ ) 
(page, line(2), A(19))(Acct#, Bought, Sold, Payment, Balance) 
(skip(3), A(6), column(14), F(7,2), column(30), F(7,2), 
column(45), F(7,2), column(60), F(7,2)); 


This PUT statement specifies the following: 


1. The heading Quarterly Statement is written on line two of a new page in the 
output file SYSPRINT. 
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FORMAT 


2. Two lines are skipped. The next line in the output is the third line following the 
heading, or the fifth iine of the repori. 


3. The following values are written: 


Acct#, beginning at character position 1 
Bought, beginning at character position 14 
Sold, beginning at character position 30 
Payment, beginning at character position 45 
Balance at character position 60. 


Example 3: \|n the following example, the value of Name is inserted in the stream 
as a character string left-adjusted in a field of N characters. 


put edit (Name,Number,City) (A(N),A(N-4),A(10)); 


Number is left-adjusted in a field of N-4 characters; and City is left-adjusted in a field 
of 10 characters. 


FORMAT statement 


The FORMAT statement specifies a format list that can be used by edit-directed 
data transmission statements to control the format of the data being transmitted. 


rt label -L_FormaT—c format - list )—;——————___9-« 


label This label constant is the same as the label-reference of the remote-format 
item, R, discussed in “R-format item” on page 282. 


format list 
is specified as described under “Edit-directed data specification” on 
page 263. 


A GET or PUT EDIT statement can include an R-format item in its format-list 
option. That portion of the format list represented by the R-format item is supplied 
by the identified FORMAT statement. 


A condition prefix associated with a FORMAT statement is invalid. 


List-directed data specification 


For information on the syntax of the LIST data specification, refer to “Data specifi- 
cation options” on page 254. 


Examples of list-directed data specifications are: 
list (Card_Rate, Dynamic_Flow) 


list (( Thickness (Distance) 
do Distance = 1 to 1000)) 


VISE CPs hy Mie RD 


List. GA*B/C, -CKFY)**2) 
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The specification in the last example can be used only for output, since it contains 
expressions. These expressions are evaluated when the statement is executed, 
and the result is placed in the stream. 


Syntax of list-directed data 


Data values in the stream, either input or output, are character or graphic represen- 
tations. The syntax for data values is: 


arithmetic-constant 


real-constant + imaginary-constant 
[ected 


character-constant 
bit-constant 
graphic-constant 





String repetition factors are not allowed. A blank must not follow a sign preceding 
a real constant, and must not precede or follow the central positive (+) or negative 
(—) symbol in complex expressions. 


The length of the data value in the stream is a function of the attributes of the data 
value, including precision and length. Detailed discussions of the conversion rules 
and their effect upon precision are listed in the descriptions of conversion to char- 

acter type in Chapter 5, “Data conversion” on page 72. 


GET list-directed 


For information about the GET statement, see “GET statement” on page 253. 


On input, data values in the stream must be separated either by a blank or by a 
comma. This separator can be surrounded by one or more blanks. A null field in 
the stream is indicated either by the first nonblank character in the data stream 
being a comma, or by two commas separated by an arbitrary number of blanks. A 
null field specifies that the value of the associated data-list item remains 
unchanged. 


Transmission of the list of constants or complex expressions on input is terminated 
by expiration of the list or at the end-of-file. For transmission of constants, the file 
is positioned in the stream ready for the next GET statement. 


If the items are separated by a comma, the first character scanned when the next 
GET statement is executed is the one immediately following the comma: 


Xbb, bHDXX 
tT 


If the items are separated by blanks only, the first item scanned is the next non- 
blank character: 


XbbHDXx xX 
tT 
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unless the end-of-record is encountered, in which case the file is positioned at the 
end of ihe record: 
XDb-DOXXX 

t 


However, if the end-of-record immediately follows a nonblank character (other than 
a comma), and the following record begins with blanks, the file is positioned at the 
first nonblank character in the following record: 


X-HDDXXX 
T 


If the record does terminate with a comma, the next record is not read until the next 
GET statement requires it. 


If the data is a character constant, the surrounding quotation marks are removed, 
and the enclosed characters are interpreted as a character string. A double quota- 
tion mark is treated as a single quotation mark. 


If the data is a bit constant, the enclosing quotation marks and the trailing character 
B are removed, and the enclosed characters are interpreted as a bit string. 


If the data is a hexadecimal constant (X, BX, B4, GX), the enclosing quotation 
marks and the suffix are removed, and the enclosed characters are interpreted as a 
hexadecimal representation of a character, bit, or graphic string. 


If the data is a mixed constant, the enclosing quotation marks and the suffix M are 
removed, and the enclosed constant is interpreted as a character string. 


If the data is a graphic constant, the enclosing quotation marks and the trailing 
character G are removed, and the enclosed graphics are interpreted as a graphic 
string. 


If the data is an arithmetic constant or complex expression, it is interpreted as 
coded arithmetic data with the base, scale, mode, and precision implied by the con- 
stant or by the rules for expression evaluation. 


PUT list-directed 


For more information about the PUT statement, see “PUT statement” on page 253. 
The values of the data-list items are converted to character representations (except 
for graphics) and transmitted to the data stream. A blank separates successive 


data values transmitted. For PRINT files, items are separated according to 
program tab settings (see “PRINT attribute” on page 270). 


Arithmetic values are converted to character. 


Binary data values are converted to decimal notation before being placed in the 
stream. 


For numeric character values, the character value is transmitted. 


Bit strings are converted to character strings. The character string is enclosed in 
quotation marks and followed by the letter B. 
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Character strings are written out as follows: 


® If the file does not have the attribute PRINT, enclosing quotation marks are 
supplied, and contained single quotation marks or apostrophes are replaced by 
two quotation marks. The field width is the current length of the string plus the 
number of added quotation marks. 


° If the file has the attribute PRINT, enclosing quotation marks are not supplied, 
and contained single quotation marks or apostrophes are unmodified. The field 
width is the current length of the string. 


Mixed strings are enclosed in SBCS quotation marks and followed by the letter M. 
Contained SBCS quotes are replaced by two quotes. 


Graphic strings are written out as follows: 


° If the file does not have the attribute PRINT, SBCS quotation marks, and the 
letter G are supplied. Because the enclosing quotation marks are SBCS, con- 
tained graphic quotation marks are represented by a single graphic quotation 
mark (unmodified). 


* If the file has the attribute PRINT, graphic quotation marks are represented by 
a single graphic quotation mark (unmodified). 


PRINT attribute 


The PRINT attribute applies to files with the STREAM and OUTPUT attributes. It 
indicates that the file is intended to be printed; that is, the data associated with the 
file is to appear on printed pages, although it can first be written on some other 
medium. 


The syntax for PRINT is: 


me —PR | M$ ________________+ « 


When PRINT is specified, the first data byte of each record of a PRINT file is 
reserved for an American National Standard (ANS) printer control character. The 
control characters are inserted by PL/I. . 


Data values transmitted by list- and data-directed data transmission are automat- 
ically aligned on the left margin and on implementation-defined preset tab positions. 


The layout of a PRINT file can be controlled by the use of the options and format 
items listed in Figure 44. 


Figure 44 (Page 1 of 2). Options and format items for PRINT files 


Edit 
Statement directed 
Statement Option format item Effect 
OPEN LINESIZE(n) = - Established line width 
OPEN PAGESIZE(n) — Establishes page length 
PUT PAGE PAGE Skip to new page 
PUT LINE(n) LINE(n) Skip to specified line 
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Figure 44 (Page 2 of 2). Options and format items for PRINT files 





Edit 
Statement directed 
Statement Option format item Effect 
PUT SKIP{[(n)] SKIP[(n)] Skip specified number of lines 
PUT - COLUMN(n) Skip to specified character position in line 
Places blank characters in line to estab- 
PUT - X(n) lish position. 


LINESIZE and PAGESIZE establish the dimensions of the printed area of the page, 
excluding footings. The LINESIZE option specifies the maximum number of char- 
acters included in each printed line. {f it is not specified for a PRINT file, a default 
value of 120 characters is used. There is no default for a non-PRINT file. The 
PAGESIZE option specifies the maximum number of lines in each printed page; if it 
is not specified, a default value of 60 lines is used. For example: 


open file(Report) output stream print PAGESIZE(55) LINESIZE(110); 
on endpage(Report) begin; 

put file(Report) skip list (Footing); 

Pageno = Pageno + 1; 

put file(Report) page list (‘Page '||Pageno); 

put file(Report) skip (3); 
end; 


The OPEN statement opens the file Report as a PRINT file. The specification 
PAGESIZE(55) indicates that each page contains a maximum of 55 lines. An 
attempt to write on a page after 55 lines have already been written (or skipped) 
raises the ENDPAGE condition. The implicit action for the ENDPAGE condition is 
to skip to a new page, but you can establish your own action through use of the 
ON statement, as shown in the example. 


LINESIZE(110) indicates that each line on the page can contain a maximum of 110 
characters. An attempt to write a line greater than 110 characters places the 
excess characters on the next line. 


When an attempt is made to write on line 56 (or to skip beyond line 55), the 
ENDPAGE condition is raised, and the begin block shown here is executed. The 
ENDPAGE condition is raised only once per page. Consequently, printing can be 
continued beyond the specified PAGESIZE after the ENDPAGE condition has been 
raised. This can be useful, for example, if you want to write a footing at the bottom 
of each page. 


The first PUT statement specifies that a line is skipped, and the value of Footing, 
presumably a character string, is printed on line 57 (when ENDPAGE is raised, the 
current line is always PAGESIZE+1). The page number, Pageno, is incremented, 
the file Report is set to the next page, and the character constant 'Page' is concat- 
enated with the new page number and printed. The final PUT statement skips 
three lines, so that the next printing will be on line 4. Control returns from the 
begin block to the PUT statement that raised the ENDPAGE condition. However, 
any SKIP or LINE option specified in that statement has no further effect. 
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DBCS data in stream I/O 


lf DBCS data is used in list-directed or data-directed transmission, the GRAPHIC 
option of the ENVIRONMENT attribute must be specified for that file. It also must 
be specified if data-directed transmission uses DBCS names even though no DBCS 
data is present. DBCS continuation rules are applied and are the same rules as 
those described in “DBCS continuation rules” on page 21. For information on how 
graphics are handled for edit-directed transmission, see “Edit-directed data 
specification” on page 263. 
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This chapter describes each of the edit-directed format items that can appear in the 
format list of a GET, PUT, or FORMAT statement. (See also “Edit-directed data 
specification” on page 263.) The format items are described in alphabetic order. 


The character (or A) format item describes the representation of a character value. 


p>p—A < 
( field-width) 


field-width 
specifies the number of character positions in the data stream that contain 
(or will contain) the string. It is an expression that is evaluated and con- 
verted to an integer value, which must be nonnegative, each time the 
format item is used. 


On input, the specified number of characters is obtained from the data stream and 
assigned, with any necessary conversion, truncation, or padding, to the data-list 
item. The field width is always required on input and, if it is zero, a null string is 
obtained. If quotation marks appear in the stream, they are treated as characters 
in the string. . 


In the example: 
get file (Infile) edit (Item) (A(20)); 


The GET statement assigns the next 20 characters in Infile to Item The value is 
converted from its character representation specified by the format item A(20), to 
the representation specified by the attributes declared for Item. 


On output, the data-list item is converted, if necessary, to a character string and is 
truncated or extended with blanks on the right to the specified field-width before 
being placed into the data stream. If the field-width is zero, no characters are 
placed into the data stream. Enclosing quotation marks are never inserted, nor are 
contained quotation marks doubled. If the field width is not specified, the default is 
equal to the character-string length of the data-list item (after conversion, if neces- 
Sary, according to the rules given in Chapter 5, “Data conversion’). 


The bit (or B) format item describes the character representation of a bit value. 
Each bit is represented by the character zero or one. 


p>—B 4 
(field-width) : 
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field-width 
specifies the number of data-stream character positions that contain (or 
will contain) the bit string. It is an expression that is evaluated and con- 
verted to an integer value, which must be nonnegative, each time the 
format item is used. 


On input, the character representation of the bit string can occur anywhere within 
the specified field. Blanks, which may appear before and after the bit string in the 
field, are ignored. Any necessary conversion occurs when the bit string is assigned 
to the data-list item. The field width is always required on input, and if it is zero, a 
null string is obtained. Any character other than 0 or 1 in the string, including 
embedded blanks, quotation marks, or the letter B, raises the CONVERSION condi- 
tion. 


On output, the character representation of the bit string is left-adjusted in the speci- 
fied field, and necessary truncation or extension with blanks occurs on the right. 
Any necessary conversion to bit-string is performed. No quotation marks are 
inserted, nor is the identifying letter B. If the field width is zero, no characters are 
placed into the data stream. If the field width is not specified, the default is equal 
to the bit-string length of the data-list item (after conversion, if necessary, according 
to the rules given in Chapter 5, “Data conversion’). 


In the example: 


declare Mask bit(25); 
put file(Maskfle) edit (Mask) (B); 


The PUT statement writes the value of Mask in Maskfle as a string of 25 characters 
consisting of zeros and ones. 


The complex (or C) format item describes the character representation of a 
complex data value. You use one real-format-item to describe both the real and 
imaginary parts of the complex data value in the data stream. 


»»>—C—( real - format - 7 ten)  ____—__—__—_____—_——_ >» 


real-format-item | 
specified by one of the F-, E-, or P-format items. The P-format item must 
describe numeric character data. 


On input, the letter | in the input raises the CONVERSION condition. 


On output, the letter | is never appended to the imaginary part. If the second real 
format item (or the first, if only one appears) is an F or E item, the sign is trans- 
mitted only if the value of the imaginary part is less than zero. If the real format 
item is a P item, the sign is transmitted only if the S or - or + picture character is 
specified. 


If you require an | to be appended, it must be specified as a separate data item in 
the data list, immediately following the variable that specifies the complex item. 
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The I, then, must have a corresponding format item (either A or P). If a second 
real format item is specified, it is ignored. 


COLUMN Format item 


The COLUMN format item positions the file to a specified character position within 
the current or following line. 


>»—COLUMN—( character-pos ition)" 7?r 


character-position 
specifies an expression which is evaluated and converted to an integer 
value, which must be nonnegative, each time the format item is used. 


The file is positioned to the specified character position in the current line, provided 
it has not already passed this position. If the file is already positioned after the 
specified character position, the current line is completed and a new line is started; 
the format item is then applied to the following line. 


Then, if the specified character position lies beyond the rightmost character position 
of the current line, or if the value of the expression for the character position is less 
than one, the default character position is one. 


The rightmost character position is determined as follows: 
* For output files, it is determined by the line size. 


° For input files, it is determined using the length of the current logical record to 
determine the line size and, hence, the rightmost character position. 


COLUMN must not be used in a GET STRING or PUT STRING statement. 
COLUMN cannot be used with input or output lines that contain graphics. 
On input, intervening character positions are ignored. 


On output, intervening character positions are filled with blanks. 


E-format item 


The floating-point (or E) format item describes the character representation of a real 
floating-point decimal arithmetic data value. 


p>—E—(—field-width, MeO OI ae ee 
,significant-digits. 





field-width 
specifies the total number of characters in the field. It is evaluated and 
converted to an integer value w each time the format item is used. 
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fractional-digits 
specifies the number of digits in the mantissa that follow the decima! point. 
It is evaluated and converted to an integer value d each time the format 
item is used. 


significant-digits 
specifies the number of digits that must appear in the mantissa. It is eval- 
uated and converted to an integer value s each time the format item is 
used. 


The following must be true: 
w >= § = dtl or w= 0 
and, when w —= 0 

s > 0, d >=0 


Note: The maximum allowed value for d is 16 for PL/I compiler for OS/2. This 
can limit the portability of your application. 


On input, either the data value in the data stream is an optionally signed real 
decimal floating-point or fixed-point constant located anywhere within the specified 
field or the CONVERSION condition is raised. (For convenience, the E preceding a 
signed exponent can be omitted.) 


The field width includes leading and trailing blanks, the exponent position, the posi- 
tions for the optional plus or minus signs, the position for the optional letter E, and 
the position for the optional decimal point in the mantissa. 


The data value can appear anywhere within the specified field; blanks can appear 
before and after the data value in the field and are ignored. If the entire field is 
blank, the CONVERSION condition is raised. When no decimal point appears, 
fractional-digits specifies the number of character positions in the mantissa to the © 
right of the assumed decimal point. If a decimal point does appear in the number, 
it overrides the specification of fractional-digits. 


If field-width is 0, there is no assignment to the data-list item. 


The statement: 
get file(A) edit (Cost) (E(10,6)); 


obtains the next 10 characters from A and interprets them as a floating-point 
decimal number. A decimal point is assumed before the rightmost 6 digits of the 
mantissa. The value of the number is converted to the attributes of COST and 
assigned to this variable. 


On output, the data-list item is converted to floating-point and rounded if necessary. 
The rounding of data is as follows: if truncation causes a digit to be lost from the 
right, and this digit is greater than or equal to 5, 1 is added to the digit to the left of 
the truncated digit. This addition might cause adjustment of the exponent. 
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The character string written in the stream for output has one of the following syn- 
taxes: 


Note: Blanks are not permitted between the elements of the character strings. 
* For d=0 


me eo. -digi Ne: 





< 


ne exponent. 
ibe eal 3 


w must be >=s+6 for positive values, or >=s+7 for negative values. 


When the value is nonzero, the exponent is adjusted so that the leading digit of 
the mantissa is nonzero. When the value is zero, zero suppression is applied 
to all digit positions (except the rightmost) of the mantissa. 


® For O<d<s 


rm» sc-aigitsL ‘ a-digits- Le + ee 


w must be >=s+7 for positive values, or >=s+8 for negative vaiues. 


When the value is nonzero, the exponent is adjusted so that the leading digit of 
the mantissa is nonzero. When the value is zero, zero suppression is applied 
to all digit positions (except the first) to the left of the decimal point. All other 
digit positions contain zero. 


© For d=s 


0.La-digitsLe 





< 


>> + exponent. 
as eee ieee ae 


w must be >=d+8 for positive values, or >=d+9 for negative values. 


When the value is nonzero, the exponent is adjusted so that the first fractional 
digit is nonzero. When the value is zero, each digit position contains zero. 


The exponent is a 4-digit integer, which can be 4 zeros. 
If the field width is such that significant digits or the sign are lost, the SIZE condi- 


tion is raised. If the character string does not fill the specified field on output, the 
character string is right-adjusted and extended on the left with blanks. 


F-format item 


The fixed-point (or F) format item describes the character representation of a real 
fixed-point decimal arithmetic value. 


p>—F—(—field-widt )-—— < 
, fractional-digits 
, scaling-factor 
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field-width 
specifies the totai number of characiers in the fieid. ii is evaiuaied and 
converted to an integer value w each time the format item is used. The 
converted value must be nonnegative. 


fractional-digits 
specifies the number of digits in the mantissa that follow the decimal point. 
It is evaluated and converted to an integer value d each time the format 
item is used. The converted value must be nonnegative. If fractional- 
digits is not specified, the default value is 0. 


scaling-factor 
specifies the number of digits that must appear in the mantissa. It is eval- 
uated and converted to an integer value p each time the format item is 
used. 


On input, either the data value in the data stream is an optionally signed real 
decimal fixed-point constant located anywhere within the specified field or the CON- 
VERSION condition is raised. Blanks can appear before and after the data value in 
‘the field and are ignored. If the entire field is blank, it is interpreted as zero. 


If no scaling-factor is specified and no decimal point appears in the field, the 
expression for fractional-digits specifies the number of digits in the data value to the 
right of the assumed decimal point. If a decimal point does appear in the data 
value, it overrides the expression for fractional-digits. 


lf a scaling-factor is specified, it effectively multiplies the data value in the data 
stream by 10 raised to the integer value (p) of the scaling-factor Thus, if p is posi- 
tive, the data value is treated as though the decimal point appeared p places to the 
right of its given position. If p is negative, the data value is treated as though the 
decimal point appeared p places to the left of its given position. The given position 
of the decimal point is that indicated either by an actual point, if it appears, or by 
the expression for fractional-digits, in the absence of an actual point. 


If the field-width is 0, there is no assignment to the data-list item. 


On output, the data-list item is converted, if necessary, to fixed-point. Floating point 
data converts to FIXED DECIMAL (N,q) where gq is the fractional-digits specified. 
The data value in the stream is the character representation of a real decimal fixed- 
point number, rounded if necessary, and right-adjusted in the specified field. 


The conversion from decimal fixed-point type to character type is performed 
according to the normal rules for conversion. Extra characters may appear as 
blanks preceding the number in the converted string. And, since leading zeros are 
converted to blanks (except for a 0 immediately to the left of the point), additional 
blanks may precede the number. If a decimal point or a minus sign appears, either 
will cause one leading blank to be replaced. 


If only the field-width is epaciied: only the integer elect of the number is written; 
no decimal point appears. 


If both the field-width and fractional-digits are specified, both the integer and frac- 
tional portions of the number are written. If the value (d) of fractional-digits is 
greater than O, a decimal point is inserted before the rightmost d digits. Trailing 
zeros are supplied when fractional-digits is less than d (the value d must be less 


Chapter 13. Edit-directed format items 279 


G-format 


G-format item 


than field-width). \f the absolute value of the item is less than 1, a O precedes the 
decimal point. Suppression of leading zeros is applied to all digit positions (except 
the first) to the left of the decimal point. 


The rounding of the data value is as follows: if truncation causes a digit to be lost 
from the right, and this digit is greater than or equal to 5, 1 is added to the digit to 
the left of the truncated digit. 


On output, if the data-list item is less than 0, a minus sign is prefixed to the char- 
acter representation; if it is greater than or equal to 0, no sign appears. Therefore, 
for negative values, the field-width might need to include provision for the sign, a 
decimal point, and a 0 before the point. 


If the field-width is such that any character is lost, the SIZE condition is raised. 


In the example: 


declare Total fixed(4,2); 
put edit (Total) (F(6,2)); 


The PUT statement specifies that the value of Total is converted to the character 
representation of a fixed-point number and written into the output file SYSPRINT. 
A decimal point is inserted before the last two numeric characters, and the number 
is right-adjusted in a field of six characters. Leading zeros are changed to blanks 
(except for a zero immediately to the left of the point), and, if necessary, a minus 
sign is placed to the left of the first numeric character. 


For the compiler, the graphic (or G) format item describes the representation of a 
graphic string. 





SS SSS See < 


| _( fieid-width) 


field-width 
specifies the number of 2-byte positions in the data stream that contain (or 
will contain) the graphic string. It is an expression that is evaluated and 
converted to an integer value, which must be nonnegative, each time the 
format item is used. End-of-line must not occur between the 2 bytes of a 
graphic. 


On input, the specified number of graphics is obtained from the data stream and 
assigned, with any necessary truncation or padding, to the data-list item. The field- 
width is always required on input, and if it is zero, a null string is obtained. 


On output, the data-list item is truncated or extended (with the padding graphic) on 
the right to the specified field-width before being placed into the data stream. No 


enclosing quotation marks are inserted, nor is the identifying suffix, G, inserted. If 


the field-width is zero, no graphics are placed into the data stream. If the field- 
width is not specified, it defaults to be equal to the graphic-string length of the data- 
list item. 
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L-format 


In the following example, if OUT does not have the GRAPHIC option, six bytes are 
transmitted. 


declare A graphic(3); 
put file(Out) edit (A) (G(3)); 


On input, L indicates that all data up to the end of the line is to be assigned to the 
data item. 


On output, L indicates that the data item, padded on the right with blanks, if neces- 
sary, is to fill the remainder of the output line. 


The syntax for the L format is: 


SS eS SS SS SS Sa 


LINE format item 


The LINE format item specifies the line on the current page of a PRINT file upon 
which the next data-list item will be printed, or it raises the ENDPAGE condition. 


»>—LINE—( ] 7ne-number ) AA _ > 


line-number 
can be represented by an expression, which is evaluated and converted to 
an integer value, which must be nonnegative, each time the format item is 
used. 


Blank lines are inserted, if necessary. 


If the specified line-number is less than or equal to the current line number, or if the 
specified line is beyond the limits set by the PAGESIZE option of the OPEN state- 
ment (or by default), the ENDPAGE condition is raised. An exception is that if the 
specified /ine-number is equal to the current line number, and the column 1 char- 
acter has not yet been transmitted, the effect is as for a SKIP(O) item, that is, a 
carriage return with no line spacing. 


If line-number is zero, it defaults to one (1). 
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P-format 


P-format item 


The picture (or P) format item describes the character representation of real 
numeric character values and of character values. 


The picture specification of the P-format item, on input, describes the form of the 
data item expected in the data stream and, in the case of a numeric character 
specification, how the item's arithmetic value is to be interpreted. If the indicated 
character does not appear in the stream, the CONVERSION condition is raised. 


On output, the value of the associated element in the data list is converted to the 
form specified by the picture specification before it is written into the data stream. 


pr>—P—' picture-speci fication’ ——_ im _ i > < 


picture-specification 
is discussed in detail in Chapter 14, “Picture specification characters.” 


Name, Total) (P'AAAAA’,P'9999'); 
When this statement is executed, the input file SYSIN is the default. The next five 


characters input from SYSIN must be alphabetic or blank and they are assigned to 
Name The next four characters must be digits and they are assigned to Total. 


PAGE format item 


The PAGE format item specifies that a new page is established. It can be used 
only with PRINT files. 


| ee —P AGE AAA eee 


Starting a new page positions the file to the first line of the next page. 


R-format item 


The remote (or R) format item specifies that the format list in a FORMAT statement 
is to be used (as described under “FORMAT statement” on page >» 267). 


r>>—R—( abel - reference) >< 


label-reference 
has as its value the label constant of a FORMAT statement. 


The R-format item and the specified FORMAT statement must be internal to the 
same block, and they must be in the same invocation of that block. 
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SKIP format 


A remote FORMAT statement cannot contain an R-format item that references itself 
as a label reterence, nor can it reference another remote FORMAT siatemeni that 
will lead to the referencing of the original FORMAT statement. 


Conditions enabled for the GET or PUT statement must also be enabled for the 
remote FORMAT statement(s) that are referred to. 


If the GET or PUT statement is the single statement of an ON-unit, that statement 
is a block, and it cannot contain a remote format item. 


Example 
declare Switch label; 
get file(In) list(Code); 
if Code = 1 then 

Switch = LI]; 
else 

Switch = L2; 
get file(In) edit (W,X,Y,Z) 

(RCSwitch)); 

Ll: format (4 F(8,3)); 
L2: format (4 E(12,6)); 


Switch has been declared a label variable. The second GET statement can be 
made to operate with either of the two FORMAT statements. 


SKIP format item 


The SKIP format item specifies that a new line is to be defined as the current line. 


pe—SKIP < 
(relative-]ine) 


relative-line 
specifies an expression, which is evaluated and converted to an integer 
value, n, each time the format item is used. The converted value must be 
nonnegative and less than 32,768. It must be greater than zero for 
non-PRINT files. If it is zero, or if it is omitted, the default is 1. 


The new line is the nth line after the present line. 


If nis greater than one, one or more lines are ignored on input; on output, one or 
more blank lines are inserted. 


The value n can be zero for PRINT files only, in which case the positioning is at the 
start of the current line. Characters previously written can be overprinted. 


For PRINT files, if the specified relative-line is beyond the limit set by the 
PAGESIZE option of the OPEN statement (or the default), the ENDPAGE condition 
is raised. 


If the SKIP format item is the first item to be executed after a file has been opened, 
output commences on the nth line of the first page. If n is zero or 1, it commences 
on the first line of the first page. 
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X-format 


For example: 


get file(In) edit(Man,Overtime) 
(skip(1), AC6), COL(60), F(4,2)); 


This statement positions the data set associated with file In to a new line. The first 
6 characters on the line are assigned to Man, and the 4 characters beginning at 
character position 60 are assigned to Overtime. 


X-format item 


The spacing (or X) format item specifies the relative spacing of data values in the 
data stream. 


p>—X—( field-width)A AA A A __—_—_—____——__ 


field-width 
specifies an expression that is evaluated and converted to an integer 
value, which must be nonnegative, each time the format item is used. The 


integer value specifies the number of characters before the next field of 
the data stream, relative to the current position in the stream. 


On input, the specified number of characters are spaced over in the data stream 
and not transmitted to the program. 


For example: 


get edit (Number, Rebate) 
CAC5 5 X05) ACSI): 


The next 15 characters from the input file, SYSIN, are treated as follows: the first 
five characters are assigned to Number, the next five characters are ignored, and 
the remaining five characters are assigned to Rebate. 


On output, the specified number of blank characters are inserted into the stream. 


In the example: 
put file(Out) edit (Part, Count) (A(4), X(2), F(5)); 


Four characters that represent the value of Part, then two blank characters, and 


finally five characters that represent the fixed-point value of Count, are placed in the 
file named Out. 
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Chapter 14. Picture specification characters 


A picture specification consists of a sequence of picture characters enclosed in 
single or double quotation marks. The characters describe the contents of each 
position of the character or numeric character data item, and the contents of the 
output. The specification can be made in two ways: 


® As part of the PICTURE attribute in a declaration 


* As part of the P-format item (described in “P-format item” on page 282) for 
edit-directed input and output. 


A picture specification describes either a character data item or a numeric character 
data item. The presence of an A or X picture character defines a picture specifica- 
tion as a character picture specification; otherwise, it is a numeric character picture 
specification. 


A character pictured item can consist of alphabetic characters, decimal digits, 
blanks, currency and punctuation characters. 


A numeric character pictured item can consist only of decimal digits, an optional 
decimal point, an optional letter E, and, optionally, one or two plus or minus signs. 
Other characters generally associated with arithmetic data, such as currency 
symbols, can also be specified, but they are not a part of the arithmetic value of the 
numeric character variable, although the characters are stored with the digits and 
are part of the character value of the variable. 


Figures in this section illustrate how different picture specifications affect the repre- 
sentation of values when assigned to a pictured variable or when printed using the 
P-format item. Each figure shows the original value of the data, the attributes of 
the variable from which it is assigned (or written), the picture specification, and the 
character value of the numeric character or pictured character variable. 


The concepts of the two types of picture specifications are described separately 
below. 


Picture repetition factor 


Repeating picture characters 


A picture repetition factor specifies the number of repetitions of the next picture 
character in the specification. 


The syntax is: 


>>—( 1.) eee 


n_ is an integer. No blanks are allowed within the parentheses. If n is 0, the 
picture character is ignored. 
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Picture characters for character data 


For example, the following picture specifications result in the same description: 


"999V99" 
"C3 )9VC2)9' 


Picture characters for character data 


A character picture specification describes a nonvarying character data item. You 
can specify that any position in the data item can contain only characters from 
certain subsets of the complete set of available characters. The data can consist of 
alphabetic characters, decimal digits, blanks, 


The only valid characters in a character picture specification are X, A, and 9. Each 
of these specifies the presence of one character position in the character value, 
which can contain the following: 


X Any character of the 256 possible bit combinations represented by the 
8-bit byte. 

A Any alphabetic or extralingual (#, @, $) character, or blank. 

9 Any digit, or blank. (Note that the 9 picture specification character allows 


blanks only for character data.) 


When a character value is assigned, or transferred, to a picture character data 
item, the particular character in each position is validated according to the corre- 
sponding picture specification character. If the character data does not match the 
specification for that position, the CONVERSION condition is raised for the invalid 
character. (However, if you change the value by record-oriented transmission or by 
using an alias, there is no checking.) For example: 


declare Part# picture 'AAA99X'; 
put edit (Part#) (P'AAA99X"); 


The following values are valid for Part#: 


"ABC12M' 
"ppb09/" 
"XYZ613' 


The following values are not valid for Part# (the invalid characters are 
underscored): 

"AB123M' 

"ABC1/2" 

"Mb#fA5 ; ' 
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Picture characters for numeric character data 


Figure 45 shows examples of character picture specifications. 


Figure 45. Character picture specification examples 


Source Data 


Source Attributes (in constant form) Picture Specification Character Value 
CHARACTER(S) '9B/2L' XXXXX 9B/2L 
CHARACTER(5) '9B/2L' XXX 9B/ 
CHARACTER(5) '9B/2L' XXXXXXX 9B/2Lbb 
CHARACTER(5) ‘ABCDE' AAAAA ABCDE 
CHARACTER(S) ‘ABCDE' AAAAAA ABCDEb 
CHARACTER(S) ‘ABCDE' AAA ABC 
CHARACTER(S) '12/34' 99X99 12/34 
CHARACTER(5) 'L26.7' A99X9 L26.7 


Picture characters for numeric character data 
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Numeric character data represents numeric values. The picture specification 
cannot contain the character data picture characters X or A. The picture characters 
for numeric character data can also specify editing of the data. 


A numeric character variable can have two values, depending upon how the vari- 
able is used. The types of values are as follows: 


Arithmetic 
The arithmetic value is the value expressed by the decimal digits of the 
data item, the assumed location of a decimal point, possibly a sign, and an 
optionally-signed exponent or scaling factor. The arithmetic value of a 
numeric character variable is used: 


* Whenever the variable appears in an expression that results in a 
coded arithmetic value or bit value (this includes expressions with the 
—, &, |, and comparison operators; even comparison with a character 
string wili use the arithmetic value of a numeric character variable) 


° Whenever the variable is assigned to a coded arithmetic, numeric 
character, or bit variable 


° When used with the C, E, F, B, and P (numeric) format items in edit- 
directed I/O. 


The arithmetic value of the numeric character variable is converted to internal 
coded arithmetic representation. 
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Picture characters for numeric character data 


Character value 
The character value is the value expressed by the decimal digits of the 
data item, as well as all of the editing and insertion characters appearing 
in the picture specification. The character value does not, however, 
include the assumed location of a decimal point, as specified by the 
picture characters V, K, or F. The character value of a numeric character 
variable is used: 


* Whenever the variable appears in a character expression 
° In an assignment to a character variable 
* Whenever the data is printed using list-directed or data-directed output 


® Whenever a reference is made to a character variable that is defined 
or based on the numeric character variable 


°* Whenever the variable is printed using edit-directed output with the A 
or P (character) format items. 


No data conversion is necessary. 


Numeric character data can contain only decimal digits, an optional decimal point, 
an optional letter E, and one or two plus or minus signs. Other characters gener- 
ally associated with arithmetic data, such as currency symbols, can also be speci- 
fied, but they are not a part of the arithmetic value of the numeric character 
variable, although the characters are stored with the digits and are part of the char- 
acter value of the variable. 


A numeric character specification consists of one or more fields, each field 
describing a fixed-point number. A floating-point specification has two fields—one 
for the mantissa and one for the exponent. The first field can be divided into sub- 
fields by inserting a V picture specification character. The data preceding the V (if 
any) and that following it (if any) are subfields of the specification. 


A requirement of the picture specification for numeric character data is that each 
field must contain at least one picture character that specifies a digit position. This 
picture character, however, need not be the digit character 9. Other picture charac- 
ters, such as the zero suppression characters (Z or *), also specify digit positions. 


Note: All characters except K, V, and F specify the occurrence of a character in 
the character representation. 

The picture characters for numeric character specifications are discussed in the fol- 
lowing sections: 


* “Digits and decimal points” on page 290 describes data specified with the 
picture characters 9 and V. 


° “Zero suppression” on page 291 describes picture data specified with the 
picture characters Z and asterisk (*). 


* “Insertion characters” on page 292 discusses the use of the insertion charac- 
ters (point, comma, slash, and B). 


* “Insertion and decimal point characters” on page 293 describes the use of the 
decimal point and insertion characters with the V picture character. 
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Digits and decimal points 


“Defining currency symbols” on page 294 describes how to define your own 
character(s) as a currency symbol, and “Signs and currency symbols” on 
page 296 describes the use of signs and currency symbols. 


“Credit, debit, and zero replacement characters.” on page 298 discusses the 
picture characters CR, DB, and Y used for credit, debit, and zero replacement 
functions. 


“Exponent characters” on page 298 discusses the picture characters K and E 
used for exponents. 


“Scaling factor’ on page 299 describes the picture character F used for scaling 
factors. 


“Picture repetition factor’ on page 286 describes the picture repetition char- 
acter. 


Digits and decimal points 


The picture characters 9 and V are used in numeric character specifications that 
represent fixed-point decimal values. 
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9 


specifies that the associated position in the data item contains a decimal 

digit. (Note that the 9 picture specification character for numeric character 

data is different from the specification for character data because the cor- 
- responding character cannot be a blank for character data.) 


A string of n 9 picture characters specifies that the item is a nonvarying 
character-string of length n, each of which is a digit (0 through 9). For 
example: 
dcl digit picture'9', 

Count picture? 999", 

XYZ picture *(10)9'; 


An example of use is: 
dcl 1 Record, 
2 Data char(72), 
2 Identification char(3), 
2 Sequence pic'99999'; 
dcl Count fixed dec(5); 


Count=Count+1 ; 
Sequence=Count ; 
write file(Output) from(Record); 


specifies that a decimal point is assumed at this position in the associated 
data item. However, it does not specify that an actual decimal point or 
decimal comma is inserted. The integer value and fractional value of the 
assigned value, after modification by the optional scaling factor F(+x), are 
aligned on the V character. Therefore, an assigned value can be trun- 
cated or extended with zero digits at either end. (If significant digits are 
truncated on the left, the result is undefined and the SIZE condition is 
raised if enabled). 


If no V character appears in the picture specification of a fixed-point 
decimal value (or in the first field of a picture specification of a floating- 
point decimal value), a V is assumed at the right end of the field specifica- 
tion. This can cause the assigned value to be truncated, if necessary, to 
an integer. 


PL/I Package/2 Language Reference 


Zero suppression 


The V character cannot appear more than once in a picture specification. 


For example: 


dcl Value picture 'Z9V999'; 
Value = 12.345; 

dcl Cvalue char(5); 

Cvalue = Value; 


Cvalue, after assignment of Value, contains '12345'. 


Figure 46 shows examples of digit and decimal point characters. 


Figure 46. Examples of digit and decimal point characters 


Source Attributes 


Source Data 


(in constant form) Picture Specification Character Value 


FIXED(5) 12345 99999 12345 
FIXED(5) 12345 99999V 12345 
FIXED(5) 12345 999V99 undefined 
FIXED(5) 12345 V99999 undefined 
FIXED(7) 1234567 99999 undefined 
FIXED(3) 123 99999 00123 
FIXED(5,2) 123.45 999V99 12345 
FIXED(7,2) 12345.67 9V9 undefined 
FIXED(5,2) 123.45 99999 00123 


Note: When the character value is undefined, the SIZE condition is raised. 


Zero suppression 


The picture characters Z and asterisk (*). specify conditional digit positions in the 
character value and can cause leading zeros to be replaced by asterisks or blanks. 
Leading zeros are those that occur in the leftmost digit positions of fixed-point 
numbers or in the leftmost digit positions of the two parts of floating-point numbers, 
that are to the left of the assumed position of a decimal point, and that are not 
preceded by any of the digits 1 through 9. The leftmost nonzero digit in a number 
and all digits, zeros or not, to the right of it represent significant digits. 


Z 


specifies a conditional digit position and causes a leading zero in the asso- 
ciated data position to be replaced by a blank. Otherwise, the digit in the 
position is unchanged. The picture character Z cannot appear in the same 
field as the picture character * or a drifting character, nor can it appear to 
the right of any of the picture characters in a field. 


specifies a conditional digit position. It is used the way the picture char- 
acter Z is used, except that leading zeros are replaced by asterisks. The 
picture character asterisk cannot appear in the same field as the picture 
character Z or a drifting character, nor can it appear to the right of any of 
the picture characters in a field. 
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Insertion characters 


Figure 47 shows examples of zero suppression characters. 


Figure 47. Examples of zero suppression characters 


Source Data 


Source Attributes (in constant form) Picture Specification Character Value 
FIXED(5) 12345 ZZZ99 12345 
FIXED(5) 00100 ZZZ99 bD100 
FIXED(5) 00100 ZZZZZ pb100 
FIXED(5) 00000 ZZZZZ Dbddb 
FIXED(5,2) 123.45 ZZZ99 pb123 
FIXED(5,2) 001.23 ZZZV99 6123 
FIXED(5) 12345 ZZZV99 undefined 
FIXED(5,2) 000.08 ZZZVZZ ppb08 
FIXED(5,2) 000.00 ZZZVZZ bddbdb 
FIXED(5) 00100 ee **100 
FIXED(5) 00000 abi “ver 
FIXED(5,2) 000.01 i dala “01 
FIXED(5,2) 95 $**9.99 . $**0.95 
FIXED(5,2) 12350 $**9.99 $123.50 


Note: When the character value is undefined, the SIZE condition is raised. 


If one of the picture characters Z or asterisk appears to the right of the picture 
character V, all fractional digit positions in the specification, as well as all integer 
digit positions, must use the Z or asterisk picture character, respectively. When all 
digit positions to the right of the picture character V contain zero suppression 
picture characters, fractional zeros of the value are suppressed only if all positions 
in the fractional part contain zeros and all integer positions have been suppressed. 
The character value of the data item will then consist of blanks or asterisks. No 
digits in the fractional part are replaced by blanks or asterisks if the fractional part 
contains any significant digit. 


Insertion characters 


The picture characters comma (,), point (.), slash (/), and blank (B) cause the speci- 
fied character to be inserted into the associated position of the numeric character 
data. They do not indicate digit or character positions, but are inserted between 
digits or characters. Each does, however, actually represent a character position in 
the character value, whether or not the character is suppressed. The comma, 
point, and slash are conditional insertion characters and can be suppressed within 
a sequence of zero suppression characters. The blank is an unconditional insertion 
character, It always specifies that a blank appears in the associated position. 


Insertion characters are applicable only to the character value. They specify 
nothing about the arithmetic value of the data item. They never cause decimal 
point or decimal comma alignment in the picture specifications of a fixed-point 
decimal number and are not a part of the arithmetic value of the data item. 
Decimal alignment is controlled by the picture characters V and F. 
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Insertion characters and decimal points 


Comma (,), point (.), or slash (/) 
inserts a character into the associated position of the numeric character data 
when no zero suppression occurs. If zero suppression does occur, the char- 
acter is inserted only under the following conditions: 


° When an unsuppressed digit appears to the left of the character's position 


* When a V appears immediately to the left of the character and the frac- 
tional part of the data item contains any significant digits 


* When the character is at the start of the picture specification 


® When the character is preceded only by characters that do not specify digit 
positions. 


In all other cases where zero suppression occurs, a comma, point, or slash 
insertion character is treated as a zero suppression characters identical to the 
preceding character. 


B_ specifies that a blank character be inserted into the associated position of the 
character value of the numeric character data. 


Insertion and decimal point characters 

The point, comma, or slash can be used in conjunction with the V to cause 
insertion of the point (or comma or slash) in the position that delimits the end of the 
integer portion in and the beginning of the fractional portion of a fixed-point (or 
floating-point) number, as might be desired in printing, since the V does not cause 
printing of a point. The point must immediately precede or immediately follow the 
V. If the point precedes the V, it is inserted only if an unsuppressed digit appears 
to the left of the V, even if all fractional digits are significant. If the point imme- 
diately follows the V, it is suppressed if all digits to the right of the V are sup- 
pressed, but it appears if there are any unsuppressed fractional digits (along with 
any intervening zeros). 


The following example shows decimal conventions that are used in different coun- 
tries. 


declare A picture 'Z,Z2Z,ZZZV.99', 
B picture 'Z.ZZZ.ZZZV,99', 
C picture 'ZBZZZBZZZV,99'; 

A,B,C = 1234; 

A,B,C = 1234.00; 


i 


A, B, and C represent nine-digit numbers with a decimal point or decimal comma 
assumed between the seventh and eighth digits. The actual point specified by the 
decimal point insertion character is not a part of the arithmetic value. It is, 
however, part of its character value. The two assignment statements assign the 
same character value to A, B, and C as follows: 

1,234.00 /* value of A */ 


1.234, 00 /* value of B */ 
1 234,00 /* value of C */ 


In the following example, decimal point alignment during assignment occurs on the 
character V. If Rate is printed, it appears as '762.00', but its arithmetic value is 
7.6200. . 


declare Rate picture '9V99.99'; 
Rate = 7.62; 
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Currency symbols 


Figure 48 shows examples of insertion characters. 


Figure 48. Examples of insertion characters 


Source Attributes 


FIXED(4) 
FIXED(6,2 
FIXED(4,2 


) 
) 
FIXED(4,2) 
FIXED(4,2) 
FIXED(4,2) 

) 

) 


FIXED(4,2 
FIXED(9,2 
FIXED(7,2) 


FIXED(7,2) 
FIXED(9,2) 
FIXED(6) 
FIXED(6) 


FIXED(6) 


Ney 


FIXED(6) 
FIXED(6) 


FIXED(6) 
FIXED(6) 
FIXED(6 


) 
FIXED(6) 
FIXED(3) 
FIXED(2) 


Defining currency symbols 
A currency symbol can be used as a picture character denoting a character value 


of numeric character data. This symbol can be the Dollar sign ( 


Source Data 
(in constant form) 


1234 
1234.56 
12.34 


00.03 
00.03 
12.34 


00.00 
12345667.89 
12345.67 


00123.45 
1234567.89 
123456 


000000 
000000 
000000 


123456 
123 
12 


Picture Specification Character Value 


9,999 
9,999V.99 
ZZ.NVZZ 


ZZ.VZZ 
ZZV .ZZ 
ZZV .2ZZ 


ZZV .ZZ 
9,999,999.V99 
** 999V.99 


** 999V.99 
9.999.999V 99 
99/99/99 
99-99-99 


99.9/99.9 


ZZ/ZZ/IZZ 
ZZ/ZZ/ZZ 


ZZ/ZZ/ZZ 
ex [eX LE 

** B**B** 
99B99B99 
9BB9BB9 
9BB/9BB 


1,234 
1,234.56 
12.34 


bbb03 
bb.03 
12.34 


Ddbbb 
1,234,567.89 
12,345.67 


***423.45 
1.234.567,89 
12/34/56 
10-12-88 
12.3/45.6 
pbb 12/34 
Dodbbb12 


bopdbbbb 
alas aa 0 ati 
12634656 
1Hb2bb3 
1hb/2bb 


$) or any symbol 


you choose. The symbol can be any sequence of characters enclosed in < and > 


characters. 


The syntax is for generalized currency symbol is: 


>>— Vai, ae ere ae » 





< indicates the start of the currency symbol It acts as an escape character. If 


you want to use the character <, you must specify <<. 


char 


is any character that will be part of your currency symbol(s). 


> indicates the end of the currency symbol If you want to use the character >, 
you must specify <>. 


More than one > indicates a drifting string (discussed on page 296). 
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Currency symbols 


Examples of general insertion strings include the following: 


<DM> represents the Deutschemark 
<Fr> represents the French Franc 
<K$> represents the Khalistan Dollar 


<Sur.f> represents the Surinam Guilder 


<$> represents the Dollar sign 


If the character < or > must be included in the sequence, it must be preceded by 
another <. Therefore, < acts as an escape character also. 


The entire sequence enclosed in < > represents one "symbol" and therefore repres- 
ents the character value for one numeric character. If the symbol needs to be 
represented as a drifting picture character, you specify > following the "< >" to rep- 
resent each occurrence. 


For example, 


Pic '<DM>>>.>>9,V99' 
represents a 10 character numeric picture, yielding 11 char- 
acters after assignment. 

Pic '<Sur. f>999, V99" 
represents a 7 character numeric picture, yielding 11 charac- 
ters after assignment. 

Pic '<K$>>>,>>9.V99" | 
represents a 10 character numeric picture, yielding 11 char- 
acters after assignment. 


Pic '<$>>>,>>9.V99' represents a 10 character numeric picture, yielding 10 char- 
acters after assignment. 


Pic '$$$,$$9.V99' has the same value as the previous picture specification. 


More examples of currency symbol definition include the following: 


dcl p pic’<DM>9.999,V99'; 
p = 1234.40; /* Yields 'DM1.234,40' = */ 


dcl p pic'<DM>9.999,V99'; 
p= 34.40; /* Yields "DM 34,40' */ 


dC) prpic* DM >>: 279,99". 
p = 1234.40; /* Yields 'DM1.234,40' = */ 


dcl p pic'<DM>>.>>9,V99'; 
p= 34.40; /* Yields '  DM34,40' = */ 


dcl p pic'9.999, V99<K&dollar>'; 
p = 1234.40; /* Yields '1.234,40K$'*/ 


In this chapter, the term currency symbol and the $ symbol refer to the dollar sign 
or any user-defined currency symbol. 
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Signs and currency symbols 


Signs and currency symbols 
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The picture characters S, +, and — specify signs in numeric character data. The 
picture character $ (or the currency symbol) specifies a currency symbol in the 
character value of numeric character data. Only one type of sign character can 
appear in each field. 


currency symbol 
specifies the currency symbol. 


In the following example: 

dcl Price picture '$99V.99'; 

Price = 12.45; 

The character value of Price is '$12.45'. Its arithmetic value is 12.45. 


For information on specifying a character as a currency symbol, refer to 
“Defining currency symbols” on page 294. 


Ss specifies the plus sign character (+) if the data value is >=0; otherwise, it 
specifies the minus sign character (—). The rules are identical to those for 
the currency symbol. 


in the following example: 
dcl Root picture 'S999'; 


The value 50 is held as '+050', the value 0 as '+000' and the value -243 
as '-243'. 


+ specifies the plus sign character (+) if the data value is >=0; otherwise, it 
specifies a blank. The rules are identical to those for the currency symbol. 


_ specifies the minus sign character (—) if the data value is <0; otherwise, it 
specifies a blank. The rules are identical to those for the currency symbol. 


Signs and currency symbols can be used in either a static or a drifting manner. 


Static use: Static use specifies that a si 
in the associated position. An S, +, or — used as a static character can appear to 
the right or left of all digits in the mantissa and exponent fields of a floating-point 

specification, and to the right or left of all digit positions of a fixed-point specifica- 


tion. 


hlan! 
ra manKk appears 


Drifting use: Drifting use specifies that leading zeros are to be suppressed. In 
this case, the rightmost suppressed position associated with the picture character 
will contain a sign, a blank, or a currency symbol (except that where all digit posi- 
tions are occupied by drifting characters and the value of the data item is zero, the 
drifting character is not inserted). 


A drifting character is specified by multiple use of that character in a picture field. 
The drifting character must be specified in each digit position through which it can 
drift. Drifting characters must appear in a sequence of the same drifting character, 
optionally containing a V and one of the insertion characters comma, point, slash, 
or B. Any of the insertion characters slash, comma, or point within or immediately 
following the string is part of the drifting string. The character B always causes 
insertion of a blank, wherever it appears. A V terminates the drifting string, except 
when the arithmetic value of the data item is zero; in that case, the V is ignored. A 
field of a picture specification can contain only one drifting string. A drifting string 
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cannot be preceded by a digit position nor can it occur in the same field as the 
picture characters * and Z. 


The position in the data associated with the characters slash, comma, and point 
appearing in a string of drifting characters will contain one of the following: 


* Slash, comma, or point if a significant digit appears to the left 


* The drifting symbol, if the next position to the right contains the leftmost signif- 
icant digit of the field 


° Blank, if the leftmost significant digit of the field is more than one position to the 
right. 


If a drifting string contains the drifting character n times, the string is associated 
with n-1 conditional digit positions. The position associated with the leftmost drifting 
character can contain only the drifting character or blank, never a digit. Two dif- 
ferent picture characters cannot be used in a drifting manner in the same field. 


If a drifting string contains a V within it, the V delimits the preceding portion as a 
subfield, and all digit positions of the subfield following the V must also be part of 
the drifting string that commences the second subfield. 


In the case in which all digit positions after the V contain drifting characters, sup- 
pression in the subfield occurs only if all of the integer and fractional digits are zero. 
The resulting edited data item is then all blanks (except for any insertion characters 
at the start of the field). If there are any nonzero fractional digits, the entire frac- 
tional portion appears unsuppressed. 


If, during or before assignment to a picture, the fractional digits of a decimal 
number are truncated so that the resulting value is zero, the sign inserted in the 
picture corresponds to the value of the decimal number prior to its truncation. 
Thus, the sign in the picture depends on how the decimal value was calculated. 


Figure 49 on page 297 shows examples of signs and currency symbol characters. 


Figure 49 (Page 1 of 2). Examples of signs and currency characters 


Source Data 
Source Attributes (in constant form) Picture Specification Character Value 
FIXED(5,2) 123.45 $999V.99 $123.45 
FIXED(5,2) 012.00 99$ 12$ 
FIXED(5,2) 001.23 $ZZZV .99 $bb1.23 
FIXED(5,2) 000.00 $ZZZV.ZZ pHbppbhb 
FIXED(1) 0 $$$.$$ pbpbpb 
FIXED(5,2) 123.45 $$$9V.99 $123.45 
FIXED(5,2) 001.23 $$$9V.99 hb$1.23 
FIXED(2) 12 $$$,999 pbdp$012 
FIXED(4) 1234 $$$,999 $1,234 
FIXED(5,2) 2.45 SZZZV.99 +662.45 
FIXED(5) 214 SS,SS9 hb+214 
FIXED(5) 4 SS,SS9 ppbpp—4 
FIXED(5,2) —123.45 +999V .99 $123.45 
FIXED(5,2) —123.45 —999V.99 —123.45 
FIXED(5,2) 123.45 999V.99S 123.45+ 
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Figure 49 (Page 2 of 2). Examples of signs and currency characters 


Source Attributes 


Source Data 
(in constant form) 


Picture Specification Character Value 


FIXED(5,2) 001.23 ++B+9V.99 pbb+1.23 
FIXED(5,2) 001.23 ~--9V.99 pbb1.23 
FIXED(5,2) 001.23 SSS9V.99 pb—1.23 


Credit, debit, and zero replacement characters. 


The picture characters CR, and DB cannot be used with any other sign characters 


in the same field. 


The character pairs CR (credit) and DB (debit) specify the signs of real numeric 


character data items. 


CR specifies that the associated positions will contain the letters CR if the 
value of the data is <0. Otherwise, the positions will contain two blanks. 
The characters CR can appear only to the right of all digit positions of a 


field. 


DB specifies that the associated positions will contain the letters DB if the 
value of the data is <0. Otherwise, the positions will contain two blanks. 
The characters DB can appear only to the right of all digit positions of a 


field. 


Y specifies that a zero in the specified digit position is replaced uncondi- 
tionally by the blank character. 


Figure 50 shows examples of credit, debit, overpunched, and zero replacement 


characters. 


Figure 50. Examples of credit, debit, and zero replacement characters 


Source Attributes 


Source Data 
(in constant form) 


Picture Specification Character Value 


FIXED(3) ~123 $Z.99CR $1.23CR. 
FIXED(4,2) 12.34 $ZZV.99CR $12.34bb 
FIXED(4,2) -12.34 $ZZV.99DB $12.34DB 
FIXED(4,2) 12.34 $ZZV.99DB $12.34b0 
FIXED(4) 1021 9991 102A 
FIXED(4) ~1021 Z99R 102J 
FIXED(4) 1021 99T9 10B1 
FIXED(5) 00100 YYYYY pb1bb 
FIXED(5) 10203 9Y9Y9 1b2b3 
FIXED(5,2) 000.04 YYYVY9 pbbb4 


Exponent characters 
The picture characters K and E delimit the exponent field of a numeric character 
specification that describes floating-point decimal numbers. The exponent field is 
the last field of a numeric character floating-point picture specification. The picture 
characters K and E cannot appear in the same specification. 
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K _ specifies that the exponent field appears to the right of the associated posi- 
tion. it does not specify a character in the numeric character data item. 


E __ specifies that the associated position contains the letter E, which indicates the 
start of the exponent field. 


The value of the exponent is adjusted in the character value so that the first signif- 
icant digit of the first field (the mantissa) appears in the position associated with the 
first digit specifier of the specification (even if it is a zero suppression character). 


Figure 51 shows examples of exponent characters. 


Figure 51. Examples of exponent characters 


Source Data 


Source Attributes (in constant form) Picture Specification Character Value 
FLOAT(5) .12345E06 V.99999E99 .12345E06 
FLOAT(5) .12345E-06 V.99999ES99 .12345E-06 
FLOAT(5) .12345E+06 V.99999KS99 .12345+06 
FLOAT(5) —123.45E+12 S999V.99ES99 —123.45E+12 
FLOAT(5) 001.23E-01 SSS9.V99ESSI9 +123.00Eb-3 
FLOAT(5) ; 001.23E+04 ZZZV .I9YKS9O 123.00+02 
FLOAT(5) 001.23E+04 SZ99V.99ES99 +123.00E+02 
FLOAT(5) 001.23E+04 SSSSV.99E-99 +123.00Eb02 


The picture character F specifies a picture scaling factor for fixed-point decimal 
numbers. It can appear only once at the right end of the picture specification. The 
syntax for F is: 


sia al 
+ 





F specifies the picture scaling factor. The picture scaling factor specifies 
that the decimal point in the arithmetic value of the variable is that number 
of places to the right (if the picture scaling factor is positive) or to the left 
(if negative) of its assumed position in the character value. 


The number of digits following the V picture character minus the integer 
specified with F must be between -128 and 127. 


Figure 52 shows examples of the picture scaling factor character. 


Figure 52. Examples of scaling factor characters 


Source Data 
Source Attributes (in constant form) Picture Specification Character Value 
FIXED(4,0) 1200 99F(2) 12 
FIXED(7,0) —1234500 S999VO9F(4) -12345 
FIXED(5,5) 00012 99F(-5) 12 
FIXED(6,6) 012345 999V99F(-4) 12345 
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Chapter 15. Condition handling 


While a PL/I program is running, a variety of events can occur that you can test for, 
respond to, and recover from. These events are calied conditions, and are raised 
when detected. The conditions can be unexpected errors, such as overflow, an 
input/output transmission error, or the end of a page when output is sent to be 
printed but does not print. Conditions can also be expected (for example, the end 
of an input file). A condition is also raised when a SIGNAL statement for that con- 
dition is executed. 


A condition is enabled when raising it will execute an on-unit or perform a system- 
defined action. 


An action specified to be executed when an enabled condition is raised is estab- 
lished. You control condition handling by enabling conditions and specitying the 
required action for raised conditions. 


The established action can be an ON-unit or the implicit action defined for the con- 
dition. 


When an ON-unit is invoked, it is treated as a procedure without parameters. To 
assist you in making use of ON-units, built-in functions and pseudovariables are 
provided that you can use to inquire about the cause of a condition. They are 
listed in Chapter 17, “Built-in functions, pseudovariables, and subroutines” on 
page 371. 


The implicit action for many conditions is to raise the ERROR condition. This pro- 
vides a common condition that can be used to check for a number of different con- 
ditions, rather than checking each condition separately. 


The condition handling built-in functions provide information such as the name of 
the entry point of the procedure in which the condition was raised, the character or 
Characier siring (or graphic siring) that raised a CONVERSION condition, the value 
of the key used in the last record transmitted, and so on. Some can be used as 
pseudovariables for error correction. 


The ONCODE built-in function returns an integer indicating the cause of the last 
condition. ONCODE can be used to identify the specific circumstances that raise a 
particular condition (for example, the ERROR condition). The codes corresponding 
to the conditions and errors detected are listed in “Condition codes” on page 329. 


Condition ee. 
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You can specify whether or not some conditions are enabled or disabled. If a con- 
dition is enabled, the raising of the condition executes an action. If a condition is 
disabled, the raising of the condition does not execute an action. 


Enabling and disabling can be specified for the eligible conditions by a condition 
prefix. 
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The syntax for the condition prefix is: 


See 


condition 
Some conditions are always enabled, and cannot be disabled. Some are 
enabled unless you disable them, and some are disabled unless you 
enable them. The conditions are listed in Chapter 16, “Conditions” on 
page 312. 






>> 








statement 
Condition prefixes are not valid for DECLARE, DEFAULT, DO, SELECT, 
WHEN, OTHERWISE, END, IF, ELSE, and % statements. For information 
on the scope of condition prefixes, refer to “Scope of the condition prefix” 
on page 304. 


in the following example (size): is the condition prefix. The conditional prefix indi- 
cates that the corresponding condition is enabled within the scope of the prefix. 


(size): Ll: X=CI**N) / (MHL); 


Conditions can be enabled using the condition prefix specifying the condition name. 
They can be disabled using the condition prefix specifying the condition name pre- 
ceded by NO without intervening blanks. Types and status of conditions are shown 
in Figure 53. 


Figure 53 (Page 1 of 2). Classes and status of conditions 


Class and conditions Status 
Computational (for data handling, expression evaluation, and computation) 
CONVERSION . Enabled by default 
FIXEDOVERFLOW Enabled by default 
INVALIDOP Enabled by default 
OVERFLOW Enabled by default 
UNDERFLOW Disabled by default 
ZERODIVIDE Enabled by default 
Input/Output 

ENDFILE Always enabled 
ENDPAGE Always enabled 
KEY Always enabled 
NAME Always enabled 
RECORD Always enabled 
TRANSMIT Always enabled 


UNDEFINEDFILE 


Always enabled 
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Figure 53 (Page 2 of 2). Classes and status of conditions 


Class and conditions Status 


Program checkout (for debugging a program) 


SIZE Disabled by default 
STRINGRANGE Disabled by default 
STRINGSIZE Disabled by default 
SUBSCRIPTRANGE Disabled by default 
Miscellaneous 

AREA Always enabled 
ATTENTION Always enabled 
CONDITION Always enabled 
ERROR Always enabled 
FINISH Always enabled 
STORAGE Always enabled 


When an enabled condition ts raised, it causes the established or implicit action to 
be performed. 


When a condition is disabled, its raising causes no action; the program is unaware 
that the event has occurred. 


For information about the performance effects of enabling and disabling conditions, 
refer to the PL/| Package/2 Programming Guide. 


Scope of the condition prefix 
The scope of a condition prefix (the part of the program to which it applies) is the 
statement or block to which the prefix is attached. The prefix does not necessarily 
apply to any procedures or ON-units that can be invoked in the execution of the 


statement. 


A condition prefix attached to a PACKAGE, PROCEDURE, or BEGIN statement 
applies to all the statements up to and including the corresponding END statement. 
This includes other PROCEDURE or BEGIN statements nested within that block. 


Condition status can be redefined within a block by attaching a prefix to statements 
within the block, including PROCEDURE and BEGIN statements (thus redefining 
the enabling or disabling of the condition within nested blocks). The redefinition 
applies only to the execution of the statement to which the prefix is attached. In 
the case of a nested PROCEDURE or BEGIN statement, it applies only to the block 
the statement defines, as well as any blocks contained within that block. 
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ON-units 


ON statement 


When OPTIMIZATION is in effect, conditions for the same expression that appear 
multiple times may be raised only once. In the following example, 
SUBSCRIPTRANGE for IX may be raised only once: 


Call P (55); 

(subscriptrange): P: proc (IX); 
Del (Ar; Br. Crk ClO)s 
Ar(IX) = Ar(IX) + Br(IX); 

t = Cr(Ix); 

End P; 


An implicit action exists for every condition. When an enabled condition is raised, 
the implicit action is executed unless an ON-unit for the enabled condition is estab- 
lished. 


The ON statement establishes the action to be executed for any subsequent raising 
of an enabled condition in the scope of the established condition. 


The syntax for the ON statement is: 


r>—on_t condition-L— syste; 
SNAP ON-unit 





condition 
is any one of those described in Chapter 16, “Conditions” on page 312 or 
defined with the CONDITION attribute. 


SNAP _ specifies that when the enabled condition is raised, diagnostic information 
relating to the condition is printed. The action of the SNAP option pre- 
cedes the action of the ON-unit. 


If SNAP and SYSTEM are specified, the implicit action is followed imme- 
diately by SNAP information. 


SYSTEM 
specifies that the implicit action is taken. The implicit action is not the 
same for every condition, although for most conditions a message is 
printed and the ERROR condition is raised. The implicit action for each 
condition is given in Chapter 16, “Conditions” on page 312. 


ON-unit 
specifies the action to be executed when the condition is raised and is 
enabled. The action is defined by the statement or statements in the 
ON-unit itself. The ON-unit is not executed at the time the ON statement 
is executed; it is executed only when the specified enabled condition is 
raised. 


The ON-unit can be either a single unlabeled simple statement or an unla- 
beled begin block. If it is a simple statement, it can be any statement 
except BEGIN, DECLARE, DEFAULT, DO, END, FORMAT, ITERATE, 
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Null ON-unit 


PS a — 


a # ab. 
Scope or ine 


LEAVE, OTHERWISE, PROCEDURE, RETURN, SELECT, WHEN, or % 
statements. If the ON-unit is a begin block, a RETURN statement can 
appear only within a procedure nested within the begin block; a LEAVE 
statement can appear only within a do group nested within the begin 
block. 


An ON-unit is treated as a procedure (without parameters) that is internal 
to the block in which it appears. Any names referenced in an ON-unit are 
those known in the environment in which the ON statement for that 
ON-unit was executed, rather than the environment in which the condition 
was raised. ; 


When execution of the ON-unit is complete, control generally returns to the 
block from which the ON-unit was entered. Just as with a procedure, 
control can be transferred out of an ON-unit by a GO TO statement. In 
this case, control is transferred to the point specified in the GO TO, anda 
normal return does not occur. 


The specific point to which control returns from an ON-unit varies for dif- 
ferent conditions. Normal return for each condition is described in 
Chapter 16, “Conditions” on page 312. 


The effect of a null statement ON-unit is to execute normal return from the condi- 


Use of the null ON-unit is different from disabling a condition for two reasons: 


* A null ON-unit can be specified for any condition, but not all conditions can be 
disabled. 


® Disabling a condition, if possible, can save time by avoiding any checking for 
this condition. (If a null ON-unit is specified, the PL/I must still check for the 
raising of the condition.) 


The execution of an ON statement establishes an action specification for a condi- 
tion. Once this action is established, it remains established throughout that block 
and throughout all dynamically descendent blocks until it is overridden by the exe- 
cution of another ON statement or a REVERT statement or until termination of the 
block in which the ON statement is executed. (For information on dynamically 
descendent ON-units, refer to “Dynamically descendent ON-units” on page 307.) 


When another ON statement specifies the same conditions: 


* If a later ON statement specifies the same condition as a prior ON statement 
and this later ON statement is executed in a block which is a dynamic 
descendant of the block containing the prior ON statement, the action specifica- 
tion of the prior ON statement is temporarily suspended, or stacked. It can be 
restored either by the execution of a REVERT statement, or by the termination 
of the block containing the later ON statement. 


When control returns from a block, all established actions that existed at the 
time of its activation are reestablished. This makes it impossible for a subrou- 
tine to alter the action established for the block that invoked the subroutine. 
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° If the later ON statement and the prior ON statement are internal to the same 
invocation of ine same block, the effect of the prior ON statement is logically 
nullified. No reestablishment is possible, except through execution of another 
ON statement (or re-execution of an overridden ON statement). 


Dynamically descendent ON-units 
It is possible to raise a condition during execution of an ON-unit that specifies 
another ON-unit. An ON-unit entered because a condition is either raised or sig- 
nalled in another ON-unit is a dynamically descendent ON-unit. A normal return 
from a dynamically descendent ON-unit reestablishes the environment of the 
ON-unit in which the condition was raised. 


A loop can occur if an ERROR condition raised in an ERROR ON-unit executes the 
same ERROR ON-unit, raising the ERROR condition again. To avoid a loop 
caused by this situation, use the following technique: 


on error begin; 
on error system; 


end: 


ON-units for file variables 


An ON statement that specifies a file variable refers to the file constant that is the 
current value of the variable when the ON-unit is established. 


Example 1 

del Foti le; 
G file variable; 
G=F; 


Li: on endfile(G); 
L2: on endfile(F); 


The statements labeled L1 and L2 are equivalent. 


Example 2 

declare FV file variable, 
FCl file, 
FC2 file; 

FY = FC1; 

on endfile(FVY) go to Fin; 


FV = FC2; 
read file(FC1) into (X1); 
read file(FV) into (X2); 


An ENDFILE condition raised during the first READ statement causes the ON-unit 
to be entered, because the ON-unit refers to file FC1. If the condition is raised in 
the second READ statement, however, the ON-unit is not entered, because this 
READ refers to file FC2. 
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Example 3 
E: procedure; 
declare Fl file; 


on endfile (F1) goto L1; 
call EL (Fl): 


El: procedure (F2); 
declare F2 file; 
on endfile (F2) go to L2; 
read file (Fl); 
read file (F2); 
end El; 


An end-of-file encountered for F1 in E1 causes the ON-unit for F2 in El to be 
entered. If the ON-unit in £1 was not specified, an ENDFILE condition encountered 
for either Fl or F2 would cause entry to the ON-unit for F1 in E. 


Example 4 


declare FV file variable, 
FCl file, 
FC2 file; 


do FV=FC1,FC2; 
on endfile(FV) go to Fin; 
end; 


If an ON statement specifying a file variable is executed more than once, and the 
variable has a different value each time, a different ON-unit is established at each 
execution. 


REVERT statement 


Execution of the REVERT statement in a given block cancels the ON-unit for the 
condition that executed in that block. The ON-unit that was established at the time 
ine biock was activated is then reestablished. REVERT affects only ON statements 
that are internal to the block in which the REVERT statement occurs and that have 
been executed in the same invocation of that block. 


The syntax for the REVERT statement is: 


pk RVR pondit tone : 


condition 
is any one of those described in Chapter 16, “Conditions” on page 312 or 
defined with the CONDITION attribute. 





The REVERT statement cancels an ON-unit only if both of the following conditions 
are true: 


1. An ON statement that is eligible for reversion, and that specifies a condition 
listed in the REVERT statement, was executed after the block was activated. 
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2. A REVERT statement with the specified condition was not previously executed 
in the same block. 


If either of these two conditions is not met, the REVERT statement is treated as a 
null statement. 


SIGNAL statement 


You can raise a condition by means of the SIGNAL statement. This statement can 
be used in program testing to verify the action of an ON-unit and to determine 
whether the correct action is associated with the condition. The established action 
is taken unless the condition is disabled. 


If the specified condition is disabled, the SIGNAL statement becomes equivalent to 
a null statement. 


The syntax for the SIGNAL statement is: 


»e—S1GNAL—condi t i on— ; —— A ____—_________—_—_» « 


condition 
is any condition described in Chapter 16, “Conditions” on page 312 or 
defined with the CONDITION attribute. 


RESIGNAL statement 


The RESIGNAL statement terminates the current ON-unit and allows another 
ON-unit to get control. The processing continues as if the ON-unit executing the 
RESIGNAL did not exist and was never given control. It allows multiple ON-units to 
get control for the same condition. It is valid only within an ON-unit or its dynamic 
descendants. 


The syntax for RESIGNAL is: 


p>—REST GNAL— ; A + + 


Multiple conditions 


A multiple condition is the simultaneous raising of two or more conditions. 


The conditions for which a multiple condition can occur are: 


RECORD, discussed on page 322 
TRANSMIT, discussed on page 326. 


The TRANSMIT condition is always processed first. The RECORD condition is 
ignored unless there is a normal return from the TRANSMIT ON-unit. 
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Multiple conditions are processed successively. When one of the following events 
occurs, no subsequent conditions are processed: 


* Condition processing terminates the program, through implicit. action for the 
condition, normal return from an ON-unit, or abnormal termination in the 
ON-unit. 


* A GOTO statement transfers control from an ON-unit, so that a normal return 
is not allowed. : 


CONDITION attribute 


The CONDITION attribute specifies that the declared name identifies a 
programmer-defined condition. 


The syntax for the CONDITION attribute is: 


> — COND DT $A aA ___ > 


A name ihai appears with the CONDITION condition in an ON, SIGNAL, or 
REVERT statement is contextually declared to be a condition name. 


The default scope is EXTERNAL. An example of the CONDITION condition 
appears on page 314. 
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STRINGSIZE: condition 2 6 eS howe ae ow ee Oe Se 325 
SUBSCRIPTRANGE condition ............00.0..000.0.000.0. 326 
TRANSMIT condition ..........00020020 0000000000000 0000. 326 
UNDEFINEDFILE condition .........2.02000000000000.0000. 327 
UNDERFLOW condition ...........2.020000.0.00000.000008. 328 
ZERODIVIDE condition. 20.5 dias We bod be aie RR Re er bere eS 329 
Condition COde@S: 2... 2eg-4 4 Bed CRS Grete ee Be 2 329 
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Conditions 





Chapter 16. Conditions 


This chapter describes conditions in alphabetic order. In general, the following 
information is given for each condition: 


* Status—an indication of the enabled/disabled status of the condition at the 
start of the program, and how the condition can be disabled (if possible) or 
enabled. Figure 53 on page 303 classifies the conditions into types, shows 
their status, and lists the conditions for disabling an enabled one. 


* Result—the result of the operation that raised the condition. This applies when 
the condition is disabled as well as when it is enabled. In some cases, the 
result is undefined. 


* Cause and syntax—A discussion of the condition, including the circumstances 
under which the condition can be raised. Raising conditions with the SIGNAL 
statement is discussed in “SIGNAL statement” on page 309. 


* Implicit action—the action taken when an enabled condition is raised and no 
ON-unit is currently established for the condition. 


* Normal return—the point to which control is returned as a result of the normal 
termination of the ON-unit. A GO TO statement that transfers control out of an 
ON-unit is an abnormal ON-unit termination. If a condition (except the ERROR 
condition) has been raised by the SIGNAL statement, the normal return is 
always to the statement immediately following SIGNAL. 


* Condition codes—the codes corresponding to the conditions and errors for 
which the program is checked. An explanation for each code is given under 
“Condition codes” on page 329. 


AREA condition 
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Status: AREA is always enabled. 


Result: An attempted allocation or assignment that raises the AREA condition has 
no effect. 


Cause and syntax: The AREA condition is raised in either of the following circum- 
stances: 


® When an attempt is made to allocate a based variable within an area that con- 
tains insufficient free storage for the allocation to be made. 


° When an attempt is made to perform an area assignment, and the target area 
contains insufficient storage to accommodate the allocations in the source area. 


The syntax for AREA is: 


PR 


Implicit action: A message is printed and the ERROR condition is raised. 
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ATTENTION 


Normal return: On normal return from the ON-unit, the action is as follows: 


* If the condition was raised by an allocation and the ON-unit is a null ON-unit, 
the allocation is not attempted again. 


* If the condition was raised by an allocation, the allocation is attempted again. 
Before the attempt is made, the area reference is reevaluated. Thus, if the 
ON-unit has changed the value of a pointer qualifying the reference to the inad- 
equate area so that it points to another area, the allocation is attempted again 
within the new area. 


° If the condition was raised by an area assignment, or by a SIGNAL statement, 
execution continues from the point at which the condition was raised. 


Condition codes: 360, 361, 362 


ATTENTION condition 
Status: ATTENTION is always enabled. 
Result: Raising the condition causes an ATTENTION ON-unit to be entered. If 


there is no ATTENTION ON-unit, the condition is ignored, and there is no change 
in the flow of control. 


Cause and syntax: The ATTENTION condition is raised when the user hits 
CTRL-BRK or CTRL-C to interrupt a non-Presentation Manager application. (The 
Presentation Manager does not recognize CTRL-BRK and CTRL-C.) The condition 
can also be raised by a SIGNAL ATTENTION statement. 


The MAIN procedure must be a PL/I procedure compiled with the INTERRUPT 
option. The runtime option INTERRUPT must be also be set to INTERRUPT(ON) 
to enable the ATTENTION interrupt capability. If the runtime option 
INTERRUPT(ON) is not set, use of the INTERRUPT option to enable the ATTEN- 
TION interrupt capability is invalid. 

An ATTENTION ON-unit is entered when: 


* The environment passes an interrupt request to the application program, and 
the program was compiled using the INTERRUPT option. 


® A SIGNAL ATTENTION statement is executed. In this case the compiler 
INTERRUPT option is not required. 


The syntax for ATTENTION is: 


bb ENO) —— eo 


Abbreviation: ATTN 


Implicit action: The attention is ignored. 
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CONDITION 


Normal return: On return from an ATTENTION ON-unit, processing is resumed at 


a point in the program immediately following the point at which the condition was 


raised. 


Condition code: 400 


CONDITION condition 


Status: CONDITION is always enabled. 


Result: Tne CONDITION condition allows you to establish an ON-unit that will be 
executed whenever a SIGNAL statement for the appropriate CONDITION condition 
is executed. 


As a debugging aid, the CONDITION condition can be used to establish an ON-unit 
that prints information about the current status of the program. 


Cause and syntax: The CONDITION condition is raised by a SIGNAL statement. 
The name specified in the SIGNAL statement determines which CONDITION condi- 


1 i i 1 i i thenrcnk 
tion is raised. The ON-unit can be executed from any point in the program through 


placement of a SIGNAL statement. Normal rules of name scope apply. A condi- 
tion name is external by default, but can be declared INTERNAL. 


The syntax for CONDITION is: 


>e>—CONDIT LON—( name)__—_—_-_—__________——_—__——+__—__» « 


Abbreviation: COND 


The following example shows the use of the CONDITION condition. 
dcl Test condition; 


on condition (Test) 
begin; 


end; 


The begin block is executed whenever the following statement is executed: — 
signal condition (Test); 


Implicit action: A message is printed and execution continues with the statement 
following SIGNAL. 


Normal return: Execution continues with the statement following the SIGNAL 
statement. 


Condition code: 500 
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CONVERSION 


CONVERSION condition 


Status: CONVERSION is enabled throughout the program, except within the 
scope of the NOCONVERSION condition prefix. You can use the ONSOURCE, 
ONCHAR, and ONGSOURCE pseudovariables in CONVERSION ON-units to 
correct Conversion errors. 


Result: When CONVERSION is raised, the contents of the entire result field are 
undefined. 


Cause and syntax: The CONVERSION computational condition is raised when- 
ever an invalid conversion is attempted on character data. This attempt can be 
made internally or during an input/output operation. For example, the condition is 
raised when: 


* Acharacter other than O or 1 exists in character data being converted to bit 
data. 


* Acharacter value being converted to a numeric character field, or to a coded 
arithmetic value, contains characters which are not the representation of an 
optionally signed arithmetic constant, or an expression to represent a complex 
constant. 


°* A value being converted to a character pictured item contains characters not 
allowed by the picture specification. 


The syntax for CONVERSION is: 


pe—CONVERS LON 


Abbreviation: CONV 


All conversions of character data are carried out character-by-character in a left-to- 
right sequence. The condition is raised for each invalid character. The condition is 
also raised if all the characters are blank, with the following exceptions: 


* For input with the F-format item, a value of zero is assumed 
* For input with the E-format item, be aware that sometimes the ON-unit will be 
repeatedly entered. 


When an invalid character is encountered, the current action specification for the 
condition is executed (provided that CONVERSION is not disabled). If the action 
specification is an ON-unit, the invalid character can be replaced within the unit. 
For nongraphic source data, use the ONSOURCE or ONCHAR pseudovariables. 
For graphic source data, use the ONGSOURCE pseudovariable. 


If the CONVERSION condition is raised and it is disabled, the program is in error. 
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ENDFILE 


If the CONVERSION condition is raised during conversion from graphic data to 
nongraphic data, the ONCHAR and ONSOURCE built-in functions do not contain 
valid source data. The ONGSOURCE built-in function contains the original graphic 
source data. The graphic conversion will be retried if the ONGSOURCE 
pseudovariable is used in the CONVERSION ON-unit to attempt to fix the graphic 
data that raised the CONVERSION condition. If the ONGSOURCE pseudovariable 
is not used in the CONVERSION ON-unit, the ERROR condition will be raised. 


Implicit action: A message is printed and the ERROR condition is raised. 


Normal return: |\f CONVERSION was raised on a character string source (not 
graphic source) and either ONSOURCE or ONCHAR pseudovariables are used in 
the ON-unit, the program retries the conversion on return from the ON-unit. 


lf CONVERSION was raised on a graphic source and the ONGSOURCE 
pseudovariable is used in the ON-unit, the program retries the conversion on return 
from the ON-unit. 


If the conversion error is not corrected using these pseudovariables, the program 
will loop. 


Condition codes: 600-666 


ENDFILE condition 


Status: The ENDFILE condition is always enabled. 


Result: \f the specified file is not closed after the condition is raised, subsequent 
GET or READ statements to the file are unsuccessful and cause additional 
ENDFILE conditions to be raised. 


Cause and syntax: The ENDFILE input/output condition can be raised during a 
operation by an attempt to read past the end of the file specified in the GET or 
READ statement. It applies only to SEQUENTIAL INPUT, SEQUENTIAL UPDATE, 
and STREAM INPUT files. 


The syntax for ENDFILE is: 


pr>—ENDFILE—( f7 ]e-reference)——A A > 


In record-oriented data transmission, ENDFILE is raised whenever an end of file is 
encountered during the execution of a READ statement. 


In stream-oriented data transmission, ENDFILE is raised during the execution of a 
GET statement if an end of file is encountered either before any items in the GET 
statement data list have been transmitted or between transmission of two of the 
data items. If an end of file is encountered while a data item is being processed, or 
if it is encountered while an X-format item is being processed, the ERROR condi- 
tion is raised. 


Implicit action: A message is printed and the ERROR condition is raised. 


316 PL/I Package/2 Language Reference 


ENDPAGE 


Normal return: Execution continues with the statement immediately following the 
GET or READ statement that raised the ENDFILE. 


If a file is closed in an ON-unit for this condition, the results of normal return are 
undefined. Exit from the ON-unit with the closed file must be achieved with a GO 
TO statement. 


Condition code: 70 


ENDPAGE condition 
Status: ENDPAGE is always enabled. 


Result: When ENDPAGE is raised, the current line number is one greater than 
that specified by the PAGESIZE option (default is 61) so that it is possible to con- 
tinue writing on the same page. The ON-unit can start a new page by execution of 
a PAGE option or a PAGE format item, which sets the current line to one. 


If the ON-unit does not start a new page, the current line number can increase 
indefinitely. If a subsequent LINE option or LINE format item specifies a line 
number that is less than or equal to the current line number, ENDPAGE is not 
raised, but a new page is started with the current line set to one. An exception is 
that if the current line number is equal to the specified line number, and the file is 
positioned on column one of the line, ENDPAGE is not raised. 


lf ENDPAGE is raised during data transmission, on return from the ON-unit, the 
data is written on the current line, which might have been changed by the ON-unit. 
lf ENDPAGE results from a LINE or SKIP option, on return from the ON-unit, the 
action specified by LINE or SKIP is ignored. 


Cause and syntax: The ENDPAGE input/output condition is raised when a PUT 
statement results in an attempt to start a new line beyond the limit specified for the 
current page. This limit can be specified by the PAGESIZE option in an OPEN 
statement; if PAGESIZE has not been specified, a default limit of 60 is applied. 
The attempt to exceed the limit can be made during data transmission (including 
associated format items, if the PUT statement is edit-directed), by the LINE option, 
or by the SKIP option. ENDPAGE can also be raised by a LINE option or LINE 
format item that specified a line number less than the current line number. 
ENDPAGE is raised only once per page, except when it is raised by the SIGNAL 
statement. 


The syntax for ENDPAGE is: 


>>—ENDPAGE—( f7 e-reference) ___—__________"—____> 


Implicit action: A new page is started. If the condition is signaled, execution is 
unaffected and continues with the statement following the SIGNAL statement. 


Normal return: Execution of the PUT statement continues in the manner 
described above. 


Condition code: 90 
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ERROR 


ERROR condition 


Status: ERROR is always enabled. 


Result An error message is issued if no ON-unit is active when the ERROR condi- 
tion arises or if the ON-unit does not use a GOTO (to exit the block) to recover 
from the condition. 


Cause and syntax: The ERROR condition is the implicit action for many condi- 
tions. This provides a common condition that can be used to check for a number 
of different conditions, rather than checking each condition separately. 

The ERROR condition is raised under the following circumstances: 


* As a result of the implicit action for a condition, which is to raise the ERROR 
condition. 


® As a result of the normal return action for some conditions, such as 
SUBSCRIPTRANGE CONVERSION or when no retry is attempted. 


* As a result of an error (for which there is no other PL/I-defined condition) during 


program execiuiion. 


The syntax for ERROR is: 


>> —ERRORA A > 


Implicit action 
The FINISH condition is raised. 


Normal return: The implicit action is taken. 


Condition codes: All codes 1000 and above are ERROR conditions. 


FINISH condition 


Status: FINISH is always enabled. 
Result: Control passes to the FINISH ON-unit and processing continues. 
Cause and syntax: The FINISH condition is raised during execution of a state- 
ment that would terminate the procedures. The following actions take place: 

® If the termination is normal: 


— The FINISH On-Unit, if established, is given control only if the main proce- 
dure is PL/I. 


© If the termination is abnormal: 


— The FINISH On-Unit, if established in an active block, is given control. 
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FIXEDOVERFLOW 


The syntax for FINISH is: 


ppe—F IN] SHA > 


Implicit action: No action is taken and processing continues from the point where 
the condition was raised. 


Normal return: Processing resumes at the point where the condition was raised. 
This point is the statement following the SIGNAL statement if the conditions was 
signalled. 


Condition code: 4 


FIXEDOVERFLOW condition 


Status: FIXEDOVERFLOW is enabled throughout the program, except within the 
scope of the NOFIXEDOVERFLOW condition prefix. 


Result: The result of the invalid fixed-point operation is undefined. 


Cause and syntax: The FIXEDOVERFLOW computational condition is raised 
when the length of the result of a fixed-point arithmetic operation exceeds the 
maximum length allowed by the implementation. 


The FIXEDOVERFLOW condition differs from the SIZE condition in that SIZE is 
raised when a result exceeds the declared size of a variable, while 
FIXEDOVERFLOW is raised when a result exceeds the maximum allowed by the 
computer. 


The syntax for FIXEDOVERFLOW is: 


>>—F I XEDOVERF LOW AAA ____—______________________» 


Abbreviation: FOFL 


If the FIXEDOVERFLOW condition is raised and it is disabled, the program is in 
error. 


Implicit action: A message is printed and the ERROR condition is raised. 


Normal return: Control returns to the point immediately following the point at 
which the condition was raised. 

Condition code: 310 

Note: If the SIZE condition is disabled, an attempt to assign an oversize number 
to a fixed decimal variable can raise the FXEDOVERFLOW condition. 


Because checking the result lengths requires a substantial overhead in both 
storage space and run time, the FIXEDOVERFLOW condition is primarily used for 
program testing. It can be removed for production programs. For more information 
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INVALIDOP 


on testing and production application programs, refer to the PL/I] Package/2 Pro- 
gramming Guide. 


INVALIDOP condition 


KEY condition 


Status: INVALIDOP is enabled throughout the program, except within the Scone 
of the NOINVALIDOP condition prefix. 


Result: The result of the invalid operation is undefined. 


Cause and syntax: The INVALIDOP computational condition is raised when any 
of the following are detected during the evaluation of floating-point expressions. 


Subtraction of two infinities 
Multiplication of infinity by 0 
Division of two infinities 

Division of zero by zero 

387 coprocessor invalid operations 
387 coprocessor stack faults 
Other 387 coprocessor exceptions. 


The syntax for INVALIDOP is: 


| >>— I NVAL 1 DOP A A ___________________________ > | 


Implicit action: Tne ERROR condition is raised. 


Normal return: Control returns to the point immediately following the point at 
which the condition was raised. If INVALIDOP was not signalled, continued use of 
the data related to the invalid operation can raise additional conditions. If a 387 
hardware exception occurs, continued program execution can raise additional con- 
ditions. 


Condition code: 290 


Status: KEY is always enabled. 


Result: The keyed record is undefined, and the statement in which it appears is 
ignored. 


Cause and syntax: The KEY input/output condition is raised when a record with a 
specified key cannot be found. The condition can be raised only during operations 
on keyed records. It is raised for the condition codes listed beiow. 


The syntax for KEY is: 


>>—KEY—( f7 ]e- reference) cr < 
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NAME 


When a LOCATE statement is used for data set, the KEY condition for this 
LOCATE statement is not raised until the next WRITE or LOCATE statement for 
the file, or when the file is closed. 


Implicit action: A message is printed and the ERROR condition is raised. 


Normal return: Control passes to the statement immediately following the state- 
ment that raised KEY. 


If a file is closed in an ON-unit for this condition, the results of normal return are 
undefined. Exit from the ON-unit with the closed file must be achieved with a GO 
TO statement. 


Condition codes: 50-58 


NAME condition 
Status: NAME is always enabled. 


Result: The named data is undefined. 


Cause and syntax: The NAME input/output condition can be raised only during 
execution of a data-directed GET statement with the FILE option. It is raised in any 
of the following situations: 


* The syntax is not correct, as described under “Syntax of data-directed data” on 
page 260. 


* The name is missing or invalid: 


— No counterpart is found in the data list. 

— If there is no data list, the name is not known in the block. 

A qualified name is not fully qualified. 

— More than 256 characters have been specified for a fully qualified name. 
— DBCS contains a byte outside the valid range X'41' to X'FE'. 


| 


* A subscript list is missing or invalid: 


— A subscript is missing. 

— The number of subscripts is incorrect. 

More than 10 digits are in a subscript (leading zeros ignored). 

A subscript is outside the allowed range of the current allocation of the vari- 
able. 


You can retrieve the incorrect data field by using the built-in function DATAFIELD in 
the ON-unit. 


The syntax for NAME is: 


»>—NAME—( f7 /e-reference)——— > 


Implicit action: The incorrect data field is ignored, a message is printed, and exe- 
cution of the GET statement continues. 
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OVERFLOW 


Normal return: The execution of the GET statement continues with the next name 
in the stream. | 


Condition code: 10 


OVERFLOW condition 


Status: OVERFLOW is enabled throughout the program, except within the scope 
of the NOOVERFLOW condition prefix. 


Result: The value of such an invalid floating-point number is undefined. 


Cause and syntax: The OVERFLOW computational condition is raised when the 
magnitude of a floating-point number exceeds the maximum allowed. 


The OVERFLOW condition differs from the SIZE condition in that SIZE is raised 
when a result exceeds the declared size of a variable, while OVERFLOW is raised 
when a result exceeds the maximum allowed by the computer. 


The syntax for OVERFLOW is: 


>> —OVE REFLOW A Ae 


Abbreviation: OFL 
If the OVERFLOW condition is raised and it is disabled, the program is in error. 
Implicit action: A message is printed and the ERROR condition is raised. 


Normal return: Control returns to the point immediately following the point at 
which the condition was raised. 


Condition code: 300 


RECORD condition 
Status: RECORD is always enabled. 


Result: The length prefix for the specified file can be inaccurately transmitted. 


Cause and syntax: The RECORD input/output condition is raised if the specified 
record is truncated. The condition can be raised only during a READ, WRITE, 
LOCATE, or REWRITE operation. 


pre—RECORD—( f7] e-reference) __——___—_————————__ > « 


If the SCALARVARYING option is applied to the file (It must be applied to a file 
using locate mode to transmit varying-length strings.), a 2-byte length prefix is 
transmitted with an element varying-length string. The length prefix is not reset if 
the RECORD condition is raised. If the SCALARVARYING option is not applied to 
the file, the length prefix is not transmitted. On input, the current length of a 
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SIZE condition 


SIZE 


varying-length string is set to the shorter of the record length and the maximum 
length of the string. 


Implicit action: A message is printed and the ERROR condition is raised. 


- Normal return: Execution continues with the statement immediately following the 


one for which RECORD was raised. 


If a file is closed in an ON-unit for this condition, the results of normal return are 
undefined. Exit from the ON-unit with the closed file must be achieved with a GO 
TO statement. 


Condition codes: 20-24 


Status: SIZE is disabled throughout the program, except within the scope of the 
SIZE condition prefix. 


Result: The result of the assignment is undefined. 


Cause and syntax: The SIZE computational condition is raised only when high- 
order (that is, leftmost) significant binary or decimal digits are lost in an attempted 
assignment to a variable or an intermediate result or in an input/output operation. 
This loss can result from a conversion involving different data types, different 
bases, different scales, or different precisions. The size condition is not enabled 
unless it appears in a condition prefix. 


The syntax for SIZE is: 


a a a 


SIZE is raised when the size of the value being assigned to a data item exceeds 
the declared (or default) size of the data item, even if this is not the actual size of 
the storage that the item occupies. For example, a fixed binary item of precision 
(20) will occupy a fullword in storage, but SIZE is raised if a value whose size 
exceeds FIXED BINARY(20) is assigned to it. 


Because checking sizes requires substantial overhead in both storage space and 
run time, the SIZE condition is primarily used for program testing. It can be 
removed from production programs. For more information on test and production 
application programs, refer to the PL/I Package/2 Programming Guide. 


The SIZE condition differs from the FIXEDOVERFLOW condition in that 
FIXEDOVERFLOW is raised when the size of a calculated fixed-point value 
exceeds the maximum allowed by the implementation. SIZE can be raised on 
assignment of a value regardless of whether or not FIXEDOVERFLOW was raised 
in the calculation of that value. 


If the SIZE condition is raised and it is disabled, the program is in error. 


Implicit action: A message is printed and the ERROR condition is raised. 
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STORAGE 


Normal return: Control returns to the point immediately following the point at 
which the condition was raised. 


Condition codes: 340, 341 


STORAGE condition 
Status: STORAGE is always enabled. 


Result: The result depends on the type of variable for which attempted storage 
allocation raised the condition. 


* After an ALLOCATE statement for a controlled variable, that variable's gener- 
ation is not allocated. A reference to that controlled variable results in 
accessing the generation (if any) before the ALLOCATE statement. 


* After an ALLOCATE statement for a based variable, the variable is not allo- 
cated and its associated pointer is undefined. 


Cause and syntax: The STORAGE condition allows the program to gain control 
for the failure of an ALLOCATE statement that attempted to allocate BASED or 


on 2 ome LOR 


CONTROLLED storage outside of an AREA. Failure of an ALLOCATE statement 
in an AREA raises the AREA condition. 


The ON-unit for the STORAGE condition can attempt to free allocated storage. If 
the ON-unit is unable to free sufficient storage, it can provide the necessary steps 
to terminate the program without losing diagnostic information. 


The syntax for STORAGE is: 


>>—S] ORAGEA-AA A A > 


Implicit action: The ERROR condition is raised. 


Normal return Control returns to the point immediately following the point at which 
the condition was raised. If the STORAGE condition was not signalled, but was 
caused by an ALLOCATE statement, the ALLOCATE statement that failed is 
retried. 


Condition codes: 450, 451 


STRINGRANGE condition 
Status: STRINGRANGE is disabled throughout the program, except within the 
scope of the STRINGRANGE condition prefix. 
Result: The value of the specified SUBSTR is altered. 


_ Cause and syntax: The STRINGRANGE program-checkout condition is raised 
whenever the values of the arguments to a SUBSTR reference fail to comply with 
the rules described for the SUBSTR built-in function. It is raised for each reference 
to an invalid argument. 
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STRINGSIZE 


The syntax for STRINGRANGE is: 


>> —STRINGRANGE-AAAAAAAAA__—_______________________» 


Abbreviation: STRG 


Implicit action: A message is printed and processing continues as described for 
normal return. 


Normal return: Execution continues with a revised SUBSTR reference. for which 
the value is defined as follows: 


Assuming that the length of the source string (after execution of the ON-unit, if 
specified) is k, the starting point is i, and the length of the substring is /; 
* If jis greater than k, the value is the null string. 


° If iis less than or equal to k, the value is that substring beginning at the mth 
character, bit, or graphic of the source string and extending n characters, 
bits, or graphics, where m and rn are defined by: 


M = max( I,1 ) 

N = max( 0,min( J + min(I,1) - 1,K - M+ 1 )) 
if J is specified. 

N=K-M+41 


if J is not specified. 
This means that the new arguments are forced within the limits. 


The values of / and j are established before entry to the ON-unit. They are not 
reevaluated on return from the ON-unit. 


The value of k might change in the ON-unit if the first argument of SUBSTR is a 
varying-length string. The value n is computed on return from the ON-unit using 
any new value of k. 


Condition code: 350 


STRINGSIZE condition 


Status: STRINGSIZE is disabled throughout the program, except within the scope 
of the STRINGSIZE condition prefix. 


Result: After the condition action, the truncated string is assigned to its target 
string. The right-hand characters, bits, or graphics of the source string are trun- 
cated so that the target string can accommodate the source string. 


Cause and syntax: The STRINGSIZE program-checkout condition is raised when 
you attempt to assign a string to a target with a shorter maximum length. 


Chapter 16. Conditions 325 


SUBSCRIPTRANGE 


The syntax for STRINGSIZE is: 


>&—ST RINGS T 2EA- Aa AAA AA A > 


Abbreviation: STRZ 
Implicit action: A message is printed and processing continues. 


Normal return: Execution continues from the point at which the condition was 
raised. 


Condition codes: 150, 151 


SUBSCRIPTRANGE condition 


PIMOAMDINMTMAAIAr : 


Siatus: SUBSCRIPTRANGE is disabied throughout the program, except within the 
scope of the SUBSCRIPTRANGE condition prefix. 


Result: When SUBSCRIPTRANGE has been raised, the value of the invalid sub- 
script is undefined, and, hence, the reference is also undefined. 


Cause and syntax: The SUBSCRIPTRANGE program-checkout condition is 
raised whenever a subscript is evaluated and found to lie outside its specified 
bounds. The order of raising SUBSCRIPTRANGE relative to evaluation of other 
subscripts is undefined. 


The syntax for SUBSCRIPTRANGE is: 


>> —SUBSCRI PT RANGE-AAA___________________________»« 


Abbreviation: SUBRG 
Implicit action: A message is printed and the ERROR condition is raised. 


Normal return: Normal return from a SUBSCRIPTRANGE ON-unit raises the 
ERROR condition. 


Condition codes: 520 


TRANSMIT condition 
Status: TRANSMIT is always enabled. 


Result Raising the TRANSMIT condition indicates that any data transmitted is 
potentially incorrect. 


Cause and syntax: The TRANSMIT input/output condition can be raised during 
any input/output operation. It is raised by an uncorrectable transmission error of a 
record (or of a block, if records are blocked), which is an input/output error that 
could not be corrected during execution. It can be caused by a damaged recording 
medium, or by incorrect specification or setup. 
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UNDEFINEDFILE 


The syntax for TRANSMIT is: 


p>—TRANSMIT—( f7 e-reference) « 


During input, TRANSMIT is raised after transmission of the potentially incorrect 
record. If records are blocked, TRANSMIT is raised for each subsequent record in 
the block. 


During output, TRANSMIT is raised after transmission. If records are blocked, 
transmission will occur when the block is complete rather than after each output 
statement. 


When a spanned record is being updated, the TRANSMIT condition is raised on the 
last segment of a record only. It is not raised for any subsequent records in the 
same block, although the integrity of these records cannot be assumed. 


Implicit action: A message is printed and the ERROR condition is raised. 
Normal return: Processing continues as though no error had occurred, allowing 
another condition (for example, RECORD) to be raised by the statement or data 
item that raised the TRANSMIT condition. 

If a file is closed in an ON-unit for this condition, the results of normal return are 
undefined. Exit from the ON-unit with the closed file must be achieved with a GO 
TO statement. 


Condition codes: 40-46 


UNDEFINEDFILE condition 
Status: UNDEFINEDFILE is always enabled. 
Result: Specified files are undefined to the application program. 
Cause and syntax: The UNDEFINEDFILE input/output condition is raised when- 
ever an unsuccessful attempt to open a file is made. If the attempt is made by 
means of an OPEN statement that specifies more than one file, the condition is 


raised after attempts to open all specified files. 


The syntax for UNDEFINEDFILE is: 


>>—UNDEF INEDF ILE—( fi Je-reference)-——_____________—___» « 


Abbreviation: UNDF 

if UNDEFINEDFILE is raised for more than one file in the same OPEN statement, 
ON-units are executed according to the order of appearance (taken from left to 
right) of the file names in that OPEN statement. 


lf UNDEFINEDFILE is raised by an implicit file opening in a data transmission 
statement, upon normal return from the ON-unit, processing continues with the 
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UNDERFLOW 


remainder of the data transmission statement. If the file was not opened in the 
ON-unit, the statement cannot continue and the ERROR condition is raised. 


The UNDEFINEDFILE condition is raised not only by conflicting attributes (such as 
DIRECT with PRINT), but also by: 

* Block size smaller than record size (except when records are spanned) 

* LINESIZE exceeding the maximum allowed 

* KEYLENGTH zero or not specified for creation of INDEXED data sets 


* Specifying a KEYLOC option, for an INDEXED data set, with a value resulting 
in KEYLENGTH + KEYLOC exceeding the record length 


* Specifying a V-format logical record length of less than 18 bytes for STREAM 
data sets 


* Specifying a block size that is not an integral multiple of the record size for 
FB-format records 


® Specifying a logical record length that is not at least 4 bytes smaller than the 
specified block size for VB-format records. 


Implicit action: A message is printed and the ERROR condition is raised. 


Normal return: Upon the normal completion of the final ON-unit, control is given 
to the statement immediately following the statement that raised the condition. 


Condition codes: 80-89, 91-95 


UNDERFLOW condition 


Status: UNDERFLOW is enabled throughout the program, except within the scope 
of the NOUNDERFLOW condition prefix. 


Result: The invalid floating-point value is set to 0. 


Cause and syntax: The UNDERFLOW computational condition is raised when 
the magnitude of a floating-point number is smaller than the minimum allowed. 


>>—UNDERF LOW AA Ar 


Abbreviation: UFL 


UNDERFLOW is not raised when equal numbers are subtracted (often called signif- 
icance error). 


The expression X‘-” (where Y>0) can be evaluated by taking the reciprocal of xX”; 
hence, the OVERFLOW condition might be raised instead of the UNDERFLOW 
condition. 


Implicit action: A message is printed, and execution continues from the point at 
which the condition was raised. 
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ZERODIVIDE 


Normal return: Control returns to the point immediately following the point at 
which the condition was raised. 


Condition code: 330 


ZERODIVIDE condition 
Status: ZERODIVIDE is enabled throughout the program, except within the scope 
of the NOZERODIVIDE condition prefix. 


Result: The result of a division by zero is undefined. 


Cause and syntax: The ZERODIVIDE computational condition is raised when an 
attempt is made to divide by zero. This condition is raised for fixed-point and 
floating-point division. If the numerator of a floating-point divide is also zero, 
INVALIDOP is raised. 


The syntax for ZERODIVIDE is: 


>>—ZEROD LV IDEA $$ A ____—__—__—__—__________> 


Abbreviation: ZDIV 
If the ZERODIVIDE condition is raised and it is disabled, the program is in error. 
Implicit action: A message is printed and the ERROR condition is raised. 


Normal return: Control returns to the point immediately following the point at 
which the condition was raised. 


Condition code: 320 


Condition codes 
Condition codes listed in this section reflect an aggregate of condition codes gener- 
ated by all implementations. Some might not be generated for a particular platform. 
The following is a summary of all condition codes in numerical sequence. 


3 This condition is raised if, ina SELECT group, no WHEN clause is selected 
and no OTHERWISE clause is present. 


SIGNAL FINISH, or STOP statement executed. 
SIGNAL ERROR statement executed. 

10 SIGNAL NAME statement executed. 

20 SIGNAL RECORD statement executed. 

21 Record variable smaller than record size. Either: 


* The record is larger than the variable in a READ INTO statement; the 
remainder of the record is lost. 


* The record length specified for a file with fixed-length records is larger 
than the variable in a WRITE, REWRITE, or LOCATE statement; the 
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Condition codes 


22 


23 


24 
40 
41 
42 
43 
44 
45 
46 
50 
51 
52 


53 


54 


55 


56 


remainder of the record is undefined. If the variable is a varying-length 
string, RECORD is not raised if the SCALARVARYING option is applied 
to the file. 


Record variable larger than record size. Either: 


* The record length specified for a file with fixed-length records is smaller 
than the variable in a READ INTO statement; the remainder of the vari- 
able is undefined. If the variable is a varying-length string, RECORD is 
not raised if the SCALARVARYING option is applied to the file. 


°* The maximum record length is smaller than the variable in a WRITE, 
REWRITE, or LOCATE statement. For WRITE or REWRITE, the 
remainder of the variable is lost; for LOCATE, the variable is not trans- 
mitted. 


® The variable in a WRITE or REWRITE statement indicates a zero 
length; no transmission occurs. If the variable is a varying-length string, 
RECORD is not raised if the SCALARVARYING option is applied to the 
file. 
Record variable length is either zero or too short to contain the embedded 


kay 
INNS 


The variable in a WRITE or REWRITE statement is too short to contain the 
data set embedded key; no transmission occurs. (This case currently 
applies only to indexed key-sequenced data sets.) 


Zero length record was read from a REGIONAL data set. 

SIGNAL TRANSMIT statement executed. 

Uncorrectable transmission error in output data set. 

Uncorrectable transmission error in input data set. 

Uncorrectable transmission error on output to index set. 

Uncorrectable transmission error on input from index set. 

Uncorrectable transmission error on output to indexed consecutive data set. 
Uncorrectable transmission error on input from consecutive data set. 
SIGNAL KEY statement executed. 

Key specified cannot be found. 


Attempt to add keyed record that has same key as a record already present 
in data set; or, in a REGIONAL(1) data set, attempt to write into a region 
already containing a record. 


Value of expression specified in KEYFROM option during sequential cre- 
ation of INDEXED or REGIONAL data set is less than value of previously 
specified key or region number. 


Key conversion error, possibly due to region number not being numeric 
character. 


Key specification is null string or begins (8)'1'B or a change of embedded 
key has occurred on a sequential REWRITE[FROM] for an INDEXED or 
key-sequenced data set. 


Attempt to access a record using a key that is outside the data set limits. 
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57 
58 


70 
80 
81 


82 


83 


84 


85 


86 


87 


88 


89 
90 
91 
92 


93 


94 
95 
96 
99 
150 


151 
290 


Condition codes 


No space available to add a keyed record on INDEXED insert. 


Key of record to be added lies outside the range(s) specified for the data 
set. 


SIGNAL ENDFILE statement executed. 
SIGNAL UNDEFINEDFILE statement executed. 


Conflict in file attributes exists at open time between attributes in DECLARE 
statement and those in explicit or implicit OPEN statement. 


Conflict between file attributes and physical organization of data set (for 
example, between file organization and device type), or indexed data set 
has not been loaded. 


After merging ENVIRONMENT options with DD statement and data set 
label, data set specification is incomplete; for example, block size or record 
format has not been specified. 


No DD statement associating file with a data set. 


During initialization of a DIRECT OUTPUT file associated with a 
REGIONAL data set, an input/output error occurred. 


LINESIZE greater than implementation-defined maximum, or invalid value in 
an ENVIRONMENT option. 


After merging ENVIRONMENT options with DD statement and data set 
label, conflicts exist in data set specification; the value of LRECL, BLKSIZE 
or RECSIZE are incompatible with one another or the DCB FUNCTION 
specified. 


After merging ENVIRONMENT options with DD statement and data set 
label, conflicts exist in data set specification; the resulting combination of 
MODE/FUNCTION and record format are invalid. 


Password invalid or not specified. 
SIGNAL ENDPAGE statement executed. 
ENVIRONMENT option invalid for file accessing indexed data set. 


During opening of an index data set with the BKWD option, the attempt to 
position the data set at the last record failed. 


Unidentified error detected by the operating system while opening a data 
set. 


REUSE specified for a nonreusable data set. 

Alternate index specified for an index data set is empty. 
Incorrect OS/2 environment variable. 

File cannot be opened. 


SIGNAL STRINGSIZE statement executed or STRINGSIZE condition 
occurred. 


Truncation occurred during assignment of a mixed character string. 


SIGNAL INVALIDOP statement was executed or INVALIDOP exception 
occurred. 
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300 


310 


320 


330 


340 


341 


350 


360 


600 
601 
603 
604 
605 


606 
607 
608 


609 
610 
611 


612 
613 


SIGNAL OVERFLOW statement executed or OVERFLOW condition 
occurred. 


SIGNAL FIXEDOVERFLOW statement executed or FIXEDOVERFLOW 
condition occurred. 


SIGNAL ZERODIVIDE statement executed or ZERODIVIDE condition 
occurred. 


SIGNAL UNDERFLOW statement executed or UNDERFLOW condition 
occurred. 


SIGNAL SIZE statement executed; or high-order nonzero digits have been 
lost in an assignment to a variable or temporary, or significant digits have 
been lost in an input/output operation. 


High order nonzero digits have been lost in an input/output operation. 


SIGNAL STRINGRANGE statement executed or STRINGRANGE condition 
occurred. 


Attempt to allocate a based variable within an area that contains insufficient 
free storage for allocation to be made. 


insuficient space in target area for assignmeni of source area. 
SIGNAL AREA statement executed. 

SIGNAL ATTENTION statement executed. 

SIGNAL STORAGE statement was executed. 

ALLOCATE statement failed; insufficient storage to satisfy request. 
SIGNAL CONDITION (name) statement executed. 


SIGNAL SUBSCRIPTRANGE statement executed, or subscript has been 
evaluated and found to lie outside its specified bounds. 


SIGNAL CONVERSION statement executed. 

Invalid conversion attempted during input/output of a character strina. 
Error during processing of an F-format item for a GET STRING statement. 
Error during processing of an F-format item for a GET FILE statement. 


Error during processing of an F-format item for a GET FILE statement fol- 
lowing a TRANSMIT condition. 


Error during processing of an E-format item fora GET STRING statement. 
Error during processing of an E-format item for a GET FILE statement. 


Error during processing of an E-format item for a GET FILE statement fol- 
lowing a TRANSMIT condition. 


Error during processing of a B-format item for a GET STRING statement. 
Error during processing of a B-format item for a GET FILE statement. 


Error during processing of a B-format item for a GET FILE statement fol- 
lowing TRANSMIT condition. 


Error during character value to arithmetic conversion. 


Error during character value to arithmetic conversion for a GET or PUT 
FILE statement. 
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614 


615 
616 


617 


618 
619 


620 


621 
622 
623 


624 
625 
626 


627 


628 


629 


633 
634 
635 


636 
639 


640 
641 
642 


Condition codes 


Error during character value to arithmetic conversion for a GET or PUT 
FILE siatement following a TRANSMIT condition. 


Error during character value to bit value conversion. 


Error during character value to bit value conversion for a GET or PUT FILE 
statement. 


Error during character value to bit value conversion for a GET or PUT FILE 
statement following a TRANSMIT condition. 


Error during character value to picture conversion. 


Error during character value to picture conversion for a GET or PUT FILE 
statement. 


Error during character value to picture conversion for a GET or PUT FILE 
statement following a TRANSMIT condition. 


Error in decimal P-format item fora GET STRING statement. 
Error in decimal P-format input for a GET FILE statement. 


Error in decimal P-format input for a GET FILE statement following a 
TRANSMIT condition. 


Error in character P-format input for a GET FILE statement. 
Error exists in character P-format input for a GET FILE statement. 


Error exists in character P-format input for a GET FILE statement following 
a TRANSMIT condition. 


A graphic or mixed character string encountered in a nongraphic environ- 
ment. 


A graphic or mixed character string encountered in a nongraphic environ- 
ment on input. 


A graphic or mixed character string encountered in a nongraphic environ- 
ment on input after TRANSMIT was detected. 


An invalid character detected in a X, BX, or GX string constant. 
An invalid character detected in a X, BX, or GX string constant on input. 


An invalid character detected in a X, BX, or GX string constant on input 
after TRANSMIT was detected. 


A shift character detected in a graphic string. 


During processing of a mixed character string, one of the following 
occurred: 


° A shift-in present in the SBCS portion. 

* A shift-out present in the graphic (double-byte) portion. (A shift-out 
cannot appear in either byte of a graphic character). 

* A shift-in present in the second byte of a graphic character. 


Conversion from picture contained an invalid character. 
Conversion from picture contained an invalid character on input or output. 


Conversion from picture contained an invalid character on input after 
TRANSMIT was detected. 
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643 


644 


645 


646 


647 


648 


649 


650 


0 
ai 
=k 


652 
653 


654 


655 
656 


657 


658 
659 


660 


661 
662 
663 


664 
665 
666 


1002 


Error during processing of a graphic F-format item for a GET STRING 
statement. 


Error during processing of a graphic F-format item for a GET FILE state- 
ment. 


Error during processing of a graphic F-format item for a GET FILE state- 
ment following a TRANSMIT condition. 


Error during processing of a graphic E-format item for a GET STRING 
statement. 


Error during processing of a graphic E-format item for a GET FILE state- 
ment. 


Error during processing of a graphic E-format item for a GET FILE state- 
ment following a TRANSMIT condition. 


Error during processing of a graphic B-format item for a GET STRING 
statement. 


Error during processing of a graphic B-format item for a GET FILE state- 
ment. 


Error during processing of a graphic B-format item for a GET FILE state- 
ment following TRANSMIT condition. 


Error during graphic character value to arithmetic conversion. 


Error during graphic character value to arithmetic conversion for a GET or 
PUT FILE statement. 


Error during graphic character value to arithmetic conversion for a GET or 
PUT FILE statement following a TRANSMIT condition. 


Error during graphic character value to bit value conversion. 


Error during graphic character value to bit value conversion for a GET or 
PUT FILE statement. 


Error during graphic character value to bit value conversion for a GET or 


PUT FILE statement following a TRANSMIT condition. 
Error during graphic character value to picture conversion. 


Error during graphic character value to picture conversion for a GET or PUT 
FILE statement. 


Error during graphic character value to picture conversion for a GET or PUT 
FILE statement following a TRANSMIT condition. 


Error in decimal graphic P-format item for a GET STRING statement. 
Error in decimal graphic P-format input for a GET FILE statement. 


Error in decimal graphic P-format input for a GET FILE statement following 
a TRANSMIT condition. 


Error in character graphic P-format input for a GET FILE statement. 
Error exists in character graphic P-format input for a GET FILE statement. 


Error exists in character graphic P-format input for a GET FILE statement 
following a TRANSMIT condition. 


GET or PUT STRING specifies data exceeding size of string. 
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1003 


1004 
1005 


1007 
1008 


1009 


1010 
1011 


1013 


1014 


1015 
1016 


1018 


1019 
1020 


1021 
1022 
1023 
1024 
1025 
1026 
1027 
1028 
1029 
1030 
1031 
1040 
1041 


Condition codes 


Further output prevented by TRANSMIT or KEY conditions previously 
raised for the data set. 


Attempt to use PAGE, LINE, or SKIP <= 0 for nonprint file. 


In a DISPLAY(expression) REPLY (character-reference) statement, 
expression or character-reference is zero length. 


A REWRITE or a DELETE statement not preceded by a READ. 


Unrecognized field preceding the assignment symbol in a string specified in 
a GET STRING DATA statement. 


An input/output statement specifies an operation or an option which con- 
flicts with the file attributes. 


A built-in function or pseudovariable referenced an unopened file. 


Data management detected an input/output error but is unable to provide 
any information about its cause. 


Previous input operation incomplete; REWRITE or DELETE statement 
specifies data which has been previously read in by a READ statement with 
an EVENT option, and no corresponding WAIT has been executed. 


Attempt to initiate further input/output operation when number of incomplete 
operations equals number specified by ENVIRONMENT option NCP(n) or 
by default. 


Event variable specified for an input/output operation when already in use. 


After UNDEFINEDFILE condition raised as a result of an unsuccessful 
attempt to implicitly open a file, the file was found unopened on normal 
return from the ON-unit. 


End of file or string encountered in data before end of data-list or in edit- 
directed transmission format list. 


Attempt to close file not opened in current process. 


Further input/output attempted before WAIT statement executed to ensure 
completion of previous READ. 


Attempt to access a record locked by another file in this process. 
Unable to extend indexed data set. 

Exclusive file closed while records still locked in a subtask 
Incorrect sequence of I/O operations on device-associated file. 
Insufficient virtual storage available to complete request. 

No position established in index data set. 

Record control interval already held in exclusive control. 
Requested record lies on unmounted volume. 

Attempt to reposition in index data set failed. 

An error occurred during index upgrade on a index data set. 
Invalid sequential write attempted on index data set. 

A data set open for output used all available space. 


An attempt was made to write a record containing a record delimiter. 
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1042 


1102 


1104 
1105 
1500 


1501 


1502 


1507 


1508 


1509 


1510 


1511 


1514 


1515 


1516 


1517 


1518 


1519 


Record in data set is not properly delimited. 


An error occurred in PL/I storage management. Storage to be freed was 
pointed to by an invalid address. 


An internal error occurred in PL/I library. 
Unable to create an object window. 


Computational error; short floating-point argument of SQRT built-in function 
is less than zero. 


Computational error; long floating-point argument of SQRT built-in function 
is less than zero. 


Computational error; extended floating-point argument of SQRT built-in 
function is less than zero. 


Computational error in LOG, LOG2, or LOG10 built-in function; extended 
floating-point argument is less than zero. 
r 


Computational error in LOG, LOG2, or LOG10 buiit-in function; short 


floating-point argument is less than zero. 


Computational error in LOG, LOG2 or LOG10 built-in function; long floating- 
point argument is less than zero. 


Computational error in SIN, COS, SIND, or COSD built-in function; absolute 
value of short floating-point argument exceeds (2**63) (SIN and COS) or 
(2**63)*180 (SIND and COSD). 


Computational error in SIN, COS, SIND, or COSD built-in function; absolute 
value of long floating-point argument exceeds (2**63) (SIN and COS) or 
(2**63)*180 (SIND and COSD). 


Computational error; absolute value of short floating-point argument of TAN 
or TAND built-in function is greater than or equal to (2**63). 


Computational error; absolute value of long floating-point argument of TAN 
or TAND built-in function exceeds, respectively, (2**63) or (2**63)*180. 


Computational error; short floating-point arguments of ATAN or ATAND 
built-in function both invalid. 


Computational error; long floating-point arguments of ATAN or ATAND 
built-in function both invalid. 


Computational error; absolute value of short floating-point argument of 
ATANH built-in function >1. 


Computational error; absolute value of long floating-point argument of 
ATANH built-in function >1. 


Computational error; absolute value of extended floating-point argument of 


~ ATANH built-in function >1. 


Computational error in SIN, COS, SIND, or COSD built-in function; argu- 
ment of extended floating-point argument exceeds (2**64). 


Computational error; absolute value of short floating-point argument of ASIN 
or ACOS built-in function exceeds 1. 


Computational error; absolute value of long floating-point argument of ASIN 
or ACOS built-in function exceeds 1. 
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1520 


1521 


1522 


1523 


1524 


1525 


1526 


1527 


1528 


1529 


1530 


1531 


1550 


1551 


1552 


1553 


1554 


1555 


1556 


1557 


Condition codes 


Computational error; absolute value of extended floating-point argument of 
ASIN, ACOS built-in function exceeds 7. 

Computational error; extended floating-point arguments of ATAN or ATAND 
built-in function both invalid. 


Computational error; absolute value of extended floating-point argument of 
TAN or TAND built-in function >= (2**64) or (2**64)*180, respectively. 


Computational error; absolute value of real short floating-point argument of 
SINH or COSH built-in function greater than 89.41. 


Absolute value of real long floating-point argument of SINH or COSH argu- 
ment greater than or equa! to 710.47. 


Absolute value of real extended floating-point argument of SINH or COSH 
than or equal to 11357.22. 


Computational error; absolute value of real short floating-point argument of 
COTAN or COTAND was greater than or equal to (2**63). 


Computational error; absolute value of real long floating-point argument of 
COTAN or COTAND was greater than or equal (2**63). 


Computational error; absolute value of real extended floating-point argu- 
ment of COTAN or COTAND was greater than or equal to (2**64). 


Computational error in SIN, COS, SIND, or COSD built-in function; absolute 
value of the real part of complex short floating-point argument greater than 
or equal to (2**63) 


Computational error in SIN, COS, SIND, or COSD built-in function; absolute 
value of the real part of complex long floating-point argument greater than 
or equal to (2**63). 


Computational error in SIN, COS, SIND, or COSD built-in function; absolute 
value of the real part of complex extended floating-point argument was 
greater than or equal to (2**64). 


Computational error; during exponentiation, real short floating-point base is 
zero and integer exponent is not positive. 


Computational error; during exponentiation, real long floating-point base is 
zero and integer exponent is not positive. 


Computational error; during exponentiation, real short floating-point base is 
zero and the floating-point or noninteger exponent is not positive. 


Computational error; during exponentiation, real long floating-point base is 
zero and the floating-point or noninteger exponent is not positive. 


Computational error; during exponentiation, complex short floating-point 
base is zero and integer exponent is not positive. 


Computational error; during exponentiation, complex long floating-point 
base is zero and integer exponent is not positive. 


Computational error; during exponentiation, complex short floating-point 
base is zero and floating-point or noninteger exponent is not positive and 
real. 


Computational error; during exponentiation, complex long floating-point 
base is zero and floating-point or noninteger exponent is not positive and 
real. 
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1558 


1559 


1560 


1561 


1562 


1569 


1570 


1571 


1572 


1573 


1574 


1575 


Computational error; complex short floating-point argument of ATAN or 
ATANH built-in function has value, respectively, of +11 or +1. 


Computational error; complex long floating-point argument of ATAN or 
ATANH built-in function has value, respectively, of +11 or +1. 


Computational error; during exponentiation, real extended floating-point 
base is zero and integer exponent not positive. 


Computational error; during exponentiation, real extended floating-point 
base is zero and floating-point or noninteger exponent is not positive. 


Computational error; during exponentiation, complex extended floating-point 
base is zero and-integer exponent is not positive. 


Computational error; complex extended floating-point base is zero and 
floating-point or nonintegral exponent is not positive. 


Computational error; complex extended floating-point argument of ATAN or 
ATANH built-in function has value, respectively, of +11 or +1. 


Computational error; real short floating-point argument of EXP built-in func- 
tion was less than —-87.33. 


Compuiationai error; reai iong fioating-point argument of EXP built-in func- 
tion was less than —708.39. 


Computational error; real extended floating-point argument of EXP built-in 
function was less than —11355.13. 


Computational error EXP built-in function; absolute value of the imaginary 
part of the complex short floating-point short argument greater than or equal 
to (2**63). 


Computational error EXP built-in function; absolute value of the imaginary 
part of the complex long floating-point short argument greater than or equal 
to (2**63). 


Computational error EXP built-in function; absolute value of the imaginal 
nart of the complex axtandad floatin 


INUIT LIU 19- poi 
equal to (2**64). 


Computational error GAMMA or LOGGAMMA built-in function; real short 
floating point argument is greater than 35.04 (GAMMA) or 4.085E+36 
(LOGGAMMA). 


Computational error GAMMA or LOGGAMMA built-in function; real long 
floating point argument is greater than 171.62 (GAMMA) or 2.559E+305 
(LOGGAMMA). 


Computational error GAMMA or LOGGAMMA built-in function; real 
extended floating point argument is greater than 1755.54 (GAMMA) or 
1.048E+4928 (LOGGAMMA). 


int snort argument greater than oF 


Computational error TANH built-in function; absolute value of the imaginary 
part of the complex short floating-point short argument greater than or equal 
to (2**63). 


Computational error TANH built-in function; absolute value of the imaginary 
part of the complex long floating-point short argument greater than or equal 
to (2**63). 
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1576 


1577 


1578 


1579 


1600 


1601 


1602 


1603 


1604 


1605 


1606 


1607 


1608 


1609 


1610 


1611 


1612 


1613 


1614 


1615 


Condition codes 


Computational error TANH built-in function; absolute value of the imaginary 
part of the compiex exiended floating-point short argument greater than or 
equal to (2**64). 


Computational error in LOG, LOG2, or LOG10 built-in function; real short 
floating-point argument equal to plus or minus zero. 


Computational error in LOG, LOG2, or LOG10 built-in function; real long 
floating-point argument equal to plus or minus zero. 


Computational error in LOG, LOG2, or LOG10 built-in function; real 
extended floating-point argument equal to plus zero. 


Computational error in EXP built-in function; for complex long floating-point 
arguments, the real argument was not plus or minus infinity, and the imagi- 
nary argument was not zero. 


Computational error in EXP built-in function; for complex extended floating- 
point arguments, the real argument was not plus or minus infinity, and the 
imaginary argument was not zero. 


Computational error; real part of the complex short floating-point argument 
for the EXP built-in function was not a valid IEEE number. 


Computational error; real part of the complex long floating-point argument 
for the EXP built-in function was not a valid IEEE number. 


Computational error; real part of the complex extended floating-point argu- 
ment for the EXP built-in function was not a valid IEEE number. 


Computational error; imaginary part of the complex short floating-point argu- 
ment for the EXP built-in function was not a valid IEEE number. 


Computational error; imaginary part of the complex long floating-point argu- 
ment for the EXP built-in function was not a valid IEEE number. 


Computational error; imaginary part of the complex extended floating-point 
argument for the EXP built-in function was not a valid IEEE number. 


Computational error; both parts of the complex short floating-point argument 
for the EXP built-in function were not valid IEEE numbers. 


Computational error; both parts of the complex long floating-point argument 
for the EXP built-in function were not valid IEEE numbers. 


Computational error; both parts of the complex extended floating-point argu- 
ment for the EXP built-in function were not valid IEEE numbers. 


Computational error; real short floating-point argument for EXP built-in func- 
tion greater than or equal to 88.73. 


_ Computational error; real long floating-point argument for EXP built-in func- 


tion greater than or equal to 709.79. 


Computational error; real extended floating-point argument for EXP built-in 
function greater than or equal to 11356.53. 


Computational error; real short floating-point argument for EXP built-in func- 
tion is not a valid IEEE number. 


Computational error; real long floating-point argument for EXP built-in func- 
tion is not a valid IEEE number. 


Chapter 16. Conditions 339 


Condition codes 


1616 


1617 


1618 


1619 


1620 


1621 


1622 


1623 


1624 


1625 


1626 


1627 


1628 


1629 


1630 


1631 


1650 


1651 


1652 


Computational error; real extended floating-point argument for EXP built-in 
function is not a valid IEEE number. 


Computational error in LOG built-in function; for complex short floating-point 
arguments, the real argument was not plus or minus infinity, and the imagi- 
nary argument was not zero. 


Computational error in LOG built-in function; for complex long floating-point 
arguments, the real argument was not plus or minus infinity, and the imagi- 
nary argument was not zero. 


Computational error in LOG, LOG2, or LOG10 built-in function; for complex 
extended floating-point arguments, the real argument was not plus or minus 
infinity, and the imaginary argument was not zero. 


Computational error in LOG, LOG2, or LOG10 built-in function; real part of 
complex short floating-point argument was not a valid IEEE number. 


Computational error in LOG, LOG2, or LOG10 built-in function; real part of 
complex long floating-point argument was not a valid IEEE number. 


Computational error in LOG, LOG2, or LOG10 built-in function; real part of 
complex extended floating-point argument was not a valid IEEE number. 


Computational error in LOG, LOG2, or LOG10 built-in function; imaginary 
part of complex short floating-point argument was not a valid IEEE number. 


Computational error in LOG, LOG2, or LOG10 built-in function; imaginary 
part of complex long floating-point argument was not a valid IEEE number. 


Computational error in LOG, LOG2, or LOG10 built-in function; imaginary 
part of complex extended floating-point argument was not a valid IEEE 
number. 


Computational error in LOG, LOG2, or LOG10 built-in function; both parts of © 
complex short floating-point argument were not valid IEEE numbers. 


Computational error in LOG, LOG2, or LOG10 built-in function; both parts of 
complex long floating-point argument were not valid IEEE numbers. 


Computational error in LOG, LOG2, or LOG10 built-in function; both parts of 
complex extended floating-point argument were not valid IEEE numbers. 


Computational error in LOG, LOG2, or LOG10 built-in function; real short 
floating-point argument is not a valid IEEE number. 


Computational error in LOG, LOG2, or LOG10 built-in function; real long 
floating-point argument is not a valid IEEE number. 


Computational error in LOG, LOG2, or LOG10 built-in function; real 
extended floating-point argument is not a valid IEEE number. 


Computational error; during exponentiation, real long floating-point base is 
plus or minus infinity, and real long floating-point exponent is zero. 


Computational error; during exponentiation, real extended floating-point 
base is plus or minus infinity, and real extended floating-point exponent is 
zero. 


Computational error; during exponentiation for a real short floating-point 
base with a real short floating-point exponent, the first argument was not a 
valid IEEE number. 
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Condition codes 


Computational error; during exponentiation for a real long floating-point 
base with a reai iong floating-point exponent, the first argument was not a 
valid IEEE number. 


Computational error; during exponentiation for a real extended floating-point 
base with a real extended floating-point exponent, the first argument was 
not a valid IEEE number. 


Computational error; during exponentiation for a real short floating-point 
base with a real short floating-point exponent, the second argument was not 
a valid IEEE number. 


Computational error; during exponentiation for a real long floating-point 
base with a real long floating-point exponent, the second argument was not 
a valid IEEE number. 


Computational error; during exponentiation for a real extended floating-point 
base with a real extended floating-point exponent, the second argument 
was not a valid IEEE number. 


Computational error; during exponentiation for a real short floating-point 
base with a real short floating-point exponent, both arguments were not 
valid IEEE numbers. 


Computational error; during exponentiation for a real long floating-point 
base with a real long floating-point exponent both arguments were not valid 
IEEE numbers. 


Computational error; during exponentiation for a real extended floating-point 
base with a real extended floating-point exponent, both arguments were not 
valid IEEE numbers. 


Computational error; during exponentiation for complex short floating-point 
base with integer value exponent, an argument plus or minus infinity is 
specified. 


Computational error; during exponentiation for complex long floating-point 
base with integer value exponent, an argument plus or minus infinity is 
specified. 


Computational error; during exponentiation for complex extended floating- 
point base with integer value exponent, an argument plus or minus infinity 
is specified. 


Computational error; during exponentiation for complex short floating-point 
base with integer value exponent, the real part of the complex argument is 
not a valid IEEE number. 


Computational error; during exponentiation for complex long floating-point 
base with integer value exponent, the real part of the complex argument is 
not a valid IEEE number. 


Computational error; during exponentiation for complex extended floating- 
point base with integer value exponent, the real part of the complex argu- 
ment is not a valid IEEE number. 


Computational error; during exponentiation for complex short floating-point 
base with integer value exponent, the imaginary part of the complex argu- 
ment is not a valid IEEE number. 
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Computational error; during exponentiation for complex long floating-point 
base with integer value exponent, the imaginary part of the complex argu- 
ment is not a valid IEEE number. 


Computational error; during exponentiation for complex extended floating- 
point base with integer value exponent, the imaginary part of the complex 
argument is not a valid IEEE number. 


Computational error; during exponentiation for complex short floating-point 
base with integer value exponent, both parts of the complex argument are 
not valid IEEE numbers. 


Computational error; during exponentiation for complex long floating-point 
base with integer value exponent, both parts of the complex argument are 
not valid IEEE numbers. 


Computational error; during exponentiation for complex extended floating- 
point base with integer value exponent, both parts of the complex argument 
are not valid IEEE numbers. 


Computational error; during exponentiation, integer base is zero and integer 
exponent is not positive. 


Computational error; during exponentiation, integer base is not plus or 
minus 1 and integer exponent is not positive. 


Computational error; during exponentiation, real short floating-point base 
was plus or minus infinity and integer exponent is equal to plus or minus 
zero. 


Computational error; during exponentiation, real long floating-point base 
was plus or minus infinity and integer exponent is equal to plus or minus 
zero. 


Computational error; during exponentiation, real extended floating-point 
base was plus or minus infinity and integer exponent is equal to plus or 
minus zero. 


Computational error; auring exponeniiation for a reai short tioating-point 
base with an integer exponent, the first argument was not a valid IEEE 
number. 


Computational error; during exponentiation for a real long floating-point 
base with an integer exponent, the first argument was not a valid IEEE 
number. 


Computational error; during exponentiation for a real extended floating-point 
base with an integer exponent, the first argument was not a valid IEEE 
number. 


Computational error in the EXP built-in function; for complex short floating- 
point arguments, the real argument was not plus or minus infinity, and the 
imaginary argument was not Zero. 


Computational error; during exponentiation for a complex long floating-point 
base with a complex long floating-point exponent, imaginary parts of both 
complex arguments are not valid IEEE numbers. 


Computational error; during exponentiation for a complex extended floating- 
point base with a complex extended floating-point exponent, imaginary parts 
of both complex arguments are not valid IEEE numbers. 
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Computational error; during exponentiation for a complex short floating-point 
base with a complex short floating-point exponent, reai pari of first complex 
argument and imaginary part of second complex argument are not valid 
IEEE numbers. | 


Computational error; during exponentiation for a complex long floating-point 
base with a complex long floating-point exponent, real part of first complex 
argument and imaginary part of second complex argument are not valid 
IEEE numbers. 


Computational error; during exponentiation for a complex extended floating- 
point base with a complex extended floating-point exponent, real part of first 
complex argument and imaginary part of second complex argument are not 
valid IEEE numbers. 


Computational error; during exponentiation for a complex short floating-point 
base with a complex short floating-point exponent, imaginary part of first 
complex argument and real part of second complex argument are not valid 
IEEE numbers. 


Computational error; during exponentiation for a complex long floating-point 
base with a complex long floating-point exponent, imaginary part of first 
complex argument and real part of second complex argument are not valid 
IEEE numbers. 


Computational error; during exponentiation for a complex extended floating- 
point base with a complex extended floating-point exponent, imaginary part 
of first complex argument and real part of second complex argument are 
not valid IEEE numbers. 


Computational error; during exponentiation for a complex short floating-point 
base with a complex short floating-point exponent, real part of first complex 
argument was the only valid IEEE number. 


Computational error; during exponentiation for a complex long floating-point 
base with a complex long floating-point exponent, real part of first complex 
argument was the only valid IEEE number. 


Computational error; during exponentiation for a complex extended floating- 
point base with a complex extended floating-point exponent, real part of first 
complex argument was the only valid IEEE number. 


Computational error; during exponentiation for a complex short floating-point 
base with a complex short floating-point exponent, imaginary part of first 
complex argument was the only valid IEEE number. 


Computational error; during exponentiation for a complex long floating-point 
base with a complex long floating-point exponent, imaginary part of first 
complex argument was the only valid IEEE number. . 


Computational error; during exponentiation for a complex extended floating- 
point base with a complex extended floating-point exponent, imaginary part 
of first complex argument was the only valid IEEE number. 


Computational error; during exponentiation for a complex short floating-point 
base with a complex short floating-point exponent, real part of second 
complex argument was the only valid IEEE number. 


Computational error; during exponentiation for a complex long floating-point 
base with a complex long floating-point exponent, real part of second 
complex argument was the only valid IEEE number. 
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Computational error; during exponentiation for a complex extended floating- 
point base with a complex extended floating-point exponent, real part of 
second complex argument was the only valid IEEE number. 


Computational error; during exponentiation for a complex short floating-point 
base with a complex short floating-point exponent, imaginary part of second 
complex argument was the only valid IEEE number. 


Computational error; during exponentiation for a complex long floating-point 
base with a complex long floating-point exponent, imaginary part of second 
complex argument was the only valid IEEE number. 


Computational error; during exponentiation for a complex extended floating- 
point base with a complex extended floating-point exponent, imaginary part 
of second complex argument was the only valid IEEE number. 


Computational error; during exponentiation for a complex short floating-point 
base with a complex short floating-point exponent, both parts of both 
complex arguments were not valid IEEE numbers. 


Computational error; during exponentiation for a complex long floating-point 
base with a complex long floating-point exponent, both parts of both 
compiex arguments were not valid IEEE numbers. 


Computational error; during exponentiation for a complex extended floating- 
point base with a complex extended floating-point exponent, both parts of 
both complex arguments were not valid IEEE numbers. 


Computational error; during exponentiation, real short floating-point base 
plus or minus infinity and real short floating-point exponent is an invalid 
32-bit integer. 


Computational error; during exponentiation, real long floating-point base is 
plus or minus infinity and real long floating-point exponent is an invalid 
32-bit integer. 


Computational error; during saa , real extended Healing: point 


+n al fla ntinn point a it 
base plus or minus infinity and real extended floating-point exponent is an 


invalid 32-bit integer. 


Computational error; during exponentiation, real short floating-point base 
plus 1 and real short floating-point exponent is plus or minus infinity. 


Computational error; during exponentiation, real long floating-point base + 1 
and real long floating-point exponent is plus or minus infinity. 


Computational error; during exponentiation, real extended floating-point 
base is + 1 and real extended floating-point exponent is plus or minus 
infinity. 

Computational error; during exponentiation, real short floating-point base is 
zero and real short floating-point exponent is not positive or zero. 


Computational error; during exponentiation, real long floating-point base is 
zero and real long floating-point exponent is not positive or zero. 


Computational error; during exponentiation, real short floating-point base 
plus or minus infinity and real short floating-point exponent is zero. 


Computational error; the first real short floating-point argument for SCALE 
was not a valid IEEE number. 
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Computational error; the real short floating-point argument for ASIN(X) or 
ACOS(X) was noi a valid IEEE number. 


Computational error; the real long floating-point argument for ASIN(X) or 
ACOS(X) was not a valid IEEE number. 


Computational error; the real extended floating-point argument for ASIN(X) 
or ACOS(X) was not a valid IEEE number. 


Computational error; during exponentiation for a complex short floating-point 
base with a complex short floating-point exponent, an argument exceeded 
the limit. 


Computational error; during exponentiation for a complex long floating-point 
base with a complex long floating-point exponent, an argument exceeded 
the limit. 


Computational error; during exponentiation for a complex extended floating- 
point base with a complex extended floating-point exponent, an argument 
exceeded the limit. 


Computational error; during exponentiation for a complex short floating-point 
base with a complex short floating-point exponent, plus or minus infinity 
was specified as an argument. 


Computational error; during exponentiation for a complex long floating-point 
base with a complex long floating-point exponent, plus or minus infinity was 
specified as an argument. 


Computational error; during exponentiation for a complex extended floating- 
point base with a complex extended floating-point exponent, plus or minus 
infinity was specified as an argument. 


Computational error; during exponentiation for a complex short floating-point 
base with a complex short floating-point exponent, the real part of the first 
complex argument is not a valid IEEE number. 


Computational error; during exponentiation for a complex long floating-point 
base with a complex long floating-point exponent, the real part of the first 
complex argument is not a valid IEEE number. 


Computational error; during exponentiation for a complex extended floating- 
point base with a complex extended floating-point exponent, the real part of 
the first complex argument is not a valid IEEE number. 


Computational error; during exponentiation for a complex short floating-point 
base with a complex short floating-point exponent, the real part of the 
second complex argument is not a valid IEEE number. 


Computational error; during exponentiation for a complex long floating-point 
base with a complex long floating-point exponent, the real part of the 
second complex argument is not a valid IEEE number. 


Computational error; during exponentiation for a complex extended floating- 
point base with a complex extended floating-point exponent, the real part of 
the second complex argument is not a valid IEEE number. 


Computational error; during exponentiation for a complex short floating-point 
base with a complex short floating-point exponent, the imaginary part of the 
first complex argument is not a valid IEEE number. 
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Computational error; during exponentiation for a complex long floating-point 
base with a complex long floating-point exponent, the imaginary part of the 
first complex argument is not a valid IEEE number. 


Computational error; during exponentiation for a complex extended floating- 
point base with a complex extended floating-point exponent, the imaginary 
part of the first complex argument is not a valid IEEE number. 


Computational error; during exponentiation for a complex short floating-point 
base with a complex short floating-point exponent, the imaginary part of the 
second complex argument is not a valid IEEE number. 


Computational error; during exponentiation for a complex long floating-point 
base with a complex long floating-point exponent, the imaginary part of the 
second complex argument is not a valid IEEE number. 


Computational error; during exponentiation for a complex extended floating- 
point base with a complex extended floating-point exponent, the imaginary 
part of the second complex argument is not a valid IEEE number. 


Computational error; during exponentiation for a complex short floating-point 
base with a complex short floating-point exponent, both parts of the first 


——— 


compiex argument are not vaiid iEEE numbers. 


Computational error; during exponentiation for a complex long floating-point 


base with a complex long floating-point exponent, both parts of the first 


complex argument are not valid IEEE numbers. 


Computational error; during exponentiation for a complex extended floating- 
point base with a complex extended floating-point exponent, both parts of 
the first complex argument are not valid IEEE numbers. 


Computational error; during exponentiation for a complex short floating-point 
base with a complex short floating-point exponent, both parts of the second 
complex argument are not valid IEEE numbers. 


Computational error; during exponentiation for a complex long floating-point 
base with a complex long floating-point exponent, both parts of the second 


eld VI LI OOYV 
complex argument are not valid IEEE numbers. 


Computational error; during exponentiation for a complex extended floating- 
point base with a complex extended floating-point exponent, both parts of 
the second complex argument are not valid IEEE numbers. 


Computational error; during exponentiation for a complex short floating-point 
base with a complex short floating-point exponent, real parts of both 
complex arguments are not valid IEEE numbers. 


Computational error; during exponentiation for a complex long floating-point 
base with a complex long floating-point exponent, real parts of both 
complex arguments are not valid IEEE numbers. 


Computational error; during exponentiation for a complex extended floating- 
point base with a complex extended floating-point exponent, real parts of 
both complex arguments are not valid IEEE numbers. 


Computational error; during exponentiation for a complex short floating-point 
base with a complex short floating-point exponent, imaginary parts of both 
complex arguments are not valid IEEE numbers. 


346 PL/I Package/2 Language Reference 


1800 


1801 


1802 


1803 


1804 


1808 


1809 


1810 


1811 


1812 


1813 


1814 © 


1815 


1816 


1817 


1818 


1819 


1820 


1821 


Condition codes 


Computational error in SIN, COS, SIND, or COSD built-in function; for 
complex extended fioating-point argumeni both paris of the argument was 
not a valid IEEE number. 


Computational error in SIN, COS, SIND, or COSD built-in function; absolute 
value of real short floating-point argument is not a valid IEEE number. 


Computational error in SIN, COS, SIND, or COSD built-in function; absolute 
value of real long floating-point argument is not a valid IEEE number. 


Computational error in SIN, COS, SIND, or COSD built-in function; absolute 
value of real extended floating-point argument is not a valid IEEE number. 


The calculated result of real extended floating-point arguments for TANH 
overflowed the output field. 


Computational error; for real short floating-point arguments of ATAN or 
ATAND built-in function, the first argument was not a valid IEEE number. 


Computational error; for real long floating-point arguments of ATAN or 
ATAND built-in function, the first argument was not a valid IEEE number. 


Computational error; for real extended floating-point argument of ATAN or 
ATAND built-in function, the first argument was not a valid IEEE number. 


Computational error; for real short floating-point arguments of ATAN or 
ATAND built-in function, the second argument was not a valid IEEE 
number. 


Computational error; for real long floating-point arguments of ATAN or 
ATAND built-in function, the second argument was not a valid IEEE 
number. 


Computational error; for real extended floating-point argument of ATAN or 
ATAND built-in function, the second argument was not a valid IEEE 
number. 


Computational error; both real short floating-point arguments of ATAN or 
ATAND built-in function were not valid [EEE numbers. 


Computational error; both real long floating-point arguments of ATAN or 
ATAND built-in function were not valid IEEE numbers. 


Computational error; both real extended floating-point arguments of ATAN 
or ATAND built-in function were not valid IEEE numbers. 


Computational error; complex short floating-point argument of ATAN or 
ATAND built-in function does not have value of (plus infinity, Oi) or (minus 
infinity, Oi). 


Computational error; complex long floating-point argument of ATAN or 
ATAND built-in function does not have value of (plus infinity, Oi) or (minus 
infinity, Oi). 

Computational error; complex extended floating-point argument of ATAN or 
ATAND built-in function does not have value of (plus infinity, Oi) or (minus 
infinity, Oi). 

Computational error; real part of complex short floating-point argument of 
ATAN or ATAND built-in function is not a valid IEEE number. 


Computational error; real part of complex long floating-point argument of 
ATAN or ATAND built-in function is not a valid IEEE number. 
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Computational error; real part of complex extended floating-point argument 
of ATAN or ATAND built-in function is not a valid IEEE number. 


Computational error; imaginary part of complex short floating-point argu- 
ment of ATAN or ATAND built-in function is not a valid IEEE number. 


Computational error; imaginary part of complex long floating-point argument 
of ATAN or ATAND built-in function is not a valid IEEE number. 


Computational error; imaginary part of complex extended floating-point 
argument of ATAN or ATAND built-in function is not a valid IEEE number. 


Computational error; both parts of complex short floating-point argument of 
ATAN or ATAND built-in function were not valid IEEE numbers. 


Computational error; both parts of complex long floating-point argument of 
ATAN or ATAND built-in function were not valid IEEE numbers. 


Computational error; both parts of complex extended floating-point argu- 
ment of ATAN or ATAND built-in function were not valid IEEE numbers. 


Computational error; the real short floating-point argument of ATAN(X) or 
ATAND(X) built-in function was not a valid IEEE number. 


Computational error; the real long floating-point argument of ATAN(X) or 
ATAND(X) built-in function was not a valid IEEE number. 


Computational error; the real extended floating-point argument of ATAN(X) 
or ATAND(X) built-in function was not a valid IEEE number. 


Computational error; real short floating-point argument of COTAN or 
COTAND was not a valid IEEE number. 


Computational error; real long floating-point argument of COTAN or 
COTAND was not a valid IEEE number. 


Computational error; real extended floating-point argument of COTAN or 
COTAND was not a valid IEEE number. 


Computational error in TAN or TAND; for complex short floating-point arau- 
ment, absolute value of the real part of argument greater than or equal to 
(2**63). 


Computational error in TAN or TAND; for complex long floating-point argu- 
ment, absolute value of the real part of argument greater than or equal to 
(2**63). 


Computational error in TAN or TAND; for complex extended floating-point 
argument, absolute value of the real part of argument greater than or equal 
to (2**64). 


Computational error in TAN or TAND; for complex short floating-point argu- 
ment both parts of the argument were plus or minus infinity. 


Computational error in TAN or TAND; for complex long floating-point argu- 
ment both parts of the argument were plus or minus infinity. 


Computational error in TAN or TAND; for complex extended floating-point 
argument both parts of the argument were plus or minus infinity. 


Computational error in TAN or TAND; for complex short floating-point argu- 
ment real part of argument not a valid IEEE number. 
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Computational error in TAN or TAND; for complex long floating-point argu- 
ment real part of argument not a valid IEEE number. 


Computational error in TAN or TAND; for complex extended floating-point 
argument real part of argument not a valid IEEE number. 


Computational error in TAN or TAND; for complex short floating-point argu- 
ment imaginary part of argument not a valid IEEE number. 


Computational error in TAN or TAND; for complex long floating-point argu- 
ment imaginary part of argument not a valid IEEE number. 


Computational error in TAN or TAND; for complex extended floating-point 
argument imaginary part of argument not a valid IEEE number. 


Computational error in TAN or TAND; for complex short floating-point argu- 
ment both parts of the argument were not valid IEEE numbers. 


Computational error in TAN or TAND; for complex long floating-point argu- 
ment both parts of the argument were not valid IEEE numbers. 


Computational error in TAN or TAND; for complex extended floating-point 
argument both parts of the argument were not valid IEEE numbers. 


Computational error in TAN or TAND; real short floating-point argument not 
a valid IEEE number. 


Computational error in TAN or TAND; real long floating-point argument not 
a valid IEEE number. 


Computational error in TAN or TAND; real extended floating-point argument 
not a valid IEEE number. 


Computational error in SIN, COS, SIND, or COSD built-in function; for 
complex short floating-point argument both parts of the argument were plus 
or minus infinity. 

Computational error in SIN, COS, SIND, or COSD built-in function; for 
complex long floating-point argument both parts of the argument were plus 
or minus infinity. 


Computational error in SIN, COS, SIND, or COSD built-in function; for 
complex extended floating-point argument both parts of the argument were 
plus or minus infinity. 


Computational error in SIN, COS, SIND, or COSD built-in function; for 
complex short floating-point argument the real part of the argument was not 
a valid IEEE number. 


Computational error in SIN, COS, SIND, or COSD built-in function; for 
complex long floating-point argument the real part of the argument was not 
a valid IEEE number. 


Computational error in SIN, COS, SIND, or COSD built-in function; for 
complex extended floating-point argument the real part of the argument was 
not a valid IEEE number. 


Computational error in SIN, COS, SIND, or COSD built-in function; for 
complex short floating-point argument the imaginary part of the argument 
was not a valid IEEE number. 


Computational error in SIN, COS, SIND, or COSD built-in function; for 
complex long floating-point argument the imaginary part of the argument 
was not a valid IEEE number. 
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Computational error in SIN, COS, SIND, or COSD built-in function; for 
complex extended floating-point argument the imaginary part of the argu- 
ment was not a valid IEEE number. 


Computational error in SIN, COS, SIND, or COSD built-in function; for 
complex short floating-point argument both parts of the argument were not 
valid IEEE numbers. 


Computational error in SIN, COS, SIND, or COSD built-in function; for 
complex long floating-point argument both parts of the argument were not 
valid IEEE numbers. 


Computational error in TANH; for complex long floating-point argument the 
real part of the argument was not equal to plus or minus infinity, and the 
imaginary part of the argument was not zero. 


Computational error in TANH; for complex extended floating-point argument 
the real part of the argument was not equal to plus or minus infinity, and 
the imaginary part of the argument was not zero. 


Computational error in TANH; for complex short floating-point argument real 
part of argument not a valid IEEE number. 


Computational error in TANH; for complex long floating-point argument real 
part of argument not a valid IEEE number. 


Computational error in TANH; for complex extended floating-point argument 
real part of argument not a valid IEEE number. 


Computational error in TANH; for complex short floating-point argument the 
imaginary part of the argument was not a valid IEEE number. 


Computational error in TANH; for complex long floating-point argument the 
imaginary part of the argument was not a valid IEEE number. 


Computational error in TANH; for complex extended floating-point argument 
the imaginary part of the argument was not a valid IEEE number. 


Computational error in TANH; for complex short floating-point argument 
both parts of the argument were not valid IEEE numbers. 


Computational error in TANH; for complex long floating-point argument both 
parts of the argument were not valid IEEE numbers. 


Computational error in TANH; for complex extended floating-point argument 
both parts of the argument were not valid IEEE numbers. 


Computational error; real short floating-point argument of TANH built-in 
function not a valid IEEE number. 


Computational error; real long floating-point argument of TANH built-in func- 
tion not a valid IEEE number. 


Computational error; real extended floating-point argument of TANH built-in 
function not a valid IEEE number. 


Computational error; absolute value of imaginary part of complex short 
floating-point argument of SINH or COSH built-in function was greater than 
or equal to (2**63). 


Computational error; absolute value of the imaginary part of complex long 
floating-point argument of SINH or COSH built-in function was greater than 
or equal to (2°*63). 
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1916 


1917 


1918 


1919 


1920 


1921 


1922 


1923 


1924 


1925 


1926 


1927 


1928 


1929 


1930 


1931 


1950 


1951 


1952 


Condition codes 


Computational error; absolute value of the imaginary part of complex 
extended floating-point argument of SINH or COSH built-in function was 
greater than or equal to (2**64). 


Computational error; for complex short floating-point argument of SINH or 
COSH built-in function real argument was not plus or minus infinity and 
imaginary argument was not zero. 


Computational error; for complex long floating-point argument of SINH or 
COSH built-in function real argument was not plus or minus infinity and 
imaginary argument was not zero. 


Computational error; for complex extended floating-point argument of SINH 
or COSH built-in function real argument was not plus or minus infinity and 
imaginary argument was not zero. 


Computational error; for complex short floating-point argument of SINH or 
COSH built-in function real part of argument not valid IEEE number. 


Computational error; for complex long floating-point argument of SINH or 
COSH built-in function real part of argument not valid IEEE number. 


Computational error; for complex extended floating-point argument of SINH 
or COSH built-in function real part of argument not valid IEEE number. 


Computational error; for complex short floating-point argument of SINH or 
COSH built-in function imaginary part of argument not valid IEEE number. 


Computational error; for complex long floating-point argument of SINH or 
COSH built-in function imaginary part of argument not valid IEEE number. 


Computational error; for complex extended floating-point argument of SINH 
or COSH built-in function imaginary part of argument not valid IEEE 
number. 


Computational error; for complex short floating-point argument of SINH or 
COSH built-in function both parts of argument not valid IEEE numbers. 


Computational error; for complex long floating-point argument of SINH or 
COSH built-in function both parts of argument not valid IEEE numbers. 


Computational error; for complex extended floating-point argument of SINH 
or COSH built-in function both parts of argument not valid IEEE numbers. 


Computational error; real short floating-point argument of SINH or COSH 
built-in function was not a valid IEEE number. 


Computational error; real long floating-point argument of SINH or COSH 
built-in function was not a valid IEEE number. 


Computational error; real extended floating-point argument of SINH or 
COSH built-in function was not a valid IEEE number. 


Computational error in SQRT; for complex extended floating-point argument 
real part was not equal to plus or minus infinity, and imaginary part was not 
equal to zero. 


Computational error in SQRT; real part of complex short floating-point argu- 
ment was not a valid IEEE number. 


Computational error in SQRT; real part of complex long floating-point argu- 
ment was not a valid IEEE number. 
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352 


1953 


1954 


1955 


1956 


1957 


1958 


1965 


1966 


1967 


1968 


1969 


1970 


1971 


1972 


1973 


1974 


Computational error in SQRT; real part of complex extended floating-point 
argument was not a valid IEEE number. 


Computational error in SQRT; imaginary part of complex short floating-point 
argument was not a valid IEEE number. 


Computational error in SQRT; imaginary part of complex long floating-point 
argument was not a valid IEEE number. 


Computational error in SQRT; imaginary part of complex extended floating- 
point argument was not a valid IEEE number. 


Computational error in SQRT; both parts of complex short floating-point 
argument were not valid IEEE numbers. 


Computational error in SQRT; both parts of complex long floating-point 
argument were not valid IEEE numbers. 


Computational error in SQRT; both parts of complex extended floating-point 


argument were not valid IEEE numbers. 


Computational error in SQRT; real short floating-point argument is equal to 
minus zero. 
Compuiationai error in SQRT; reai iong fioating-point argument is equai to 
minus zero. 


Computational error in SQRT; real extended floating-point argument is 
equal to minus zero. 


Computational error in SQRT; real short floating-point argument was not a 
valid IEEE number. 


Computational error in SQRT; real long floating-point argument was not a 
valid IEEE number. 


Computational error in SQRT; real extended floating-point argument was 
not a valid IEEE number. 


Computational error; complex short floating-point argument of ATANH 
included plus or minus infinity. 


Computational error; complex long floating-point argument of ATANH 
included plus or minus infinity. 


Computational error; complex extended floating-point argument of ATANH 
included plus or minus infinity. 


Computational error; real part of complex short floating-point argument of 
ATANH was not a valid IEEE number. 


Computational error; real part of complex long floating-point argument of 
ATANH was not a valid IEEE number. 


Computational error; real part of complex extended floating-point argument 
of ATANH was not a valid IEEE number. 


Computational error; imaginary part of complex short floating-point argu- 
ment of ATANH was not a valid IEEE number. 


Computational error; imaginary part of complex long floating-point argument 
of ATANH was not a valid IEEE number. 


Computational error; imaginary part of complex extended floating-point 
argument of ATANH was not a valid IEEE number. 
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1975 


1976 


1977 


1978 


1979 


1980 


1981 


2002 


2101 
2102 


2103 
2150 


2151 


2152 


2153 


2154 


2155 


2156 


2157 


2158 


2159 


2160 


Condition codes 


Computational error; both parts of complex short floating-point argument of 
ATANH were not valid IEEE numbers. 


Computational error; both parts of complex long floating-point argument of 
ATANH were not valid IEEE numbers. 


Computational error; both parts of complex extended floating-point argu- 
ment of ATANH were not valid IEEE numbers. 


Computational error; floating-point argument of ATANH was not a valid 
IEEE number. 


Computational error; long floating-point argument of ATANH was not a valid 
IEEE number. 


Computational error; of extended floating-point argument of ATANH was not 
a valid IEEE number. 


Computational error in TANH; for complex short floating-point argument the 
real part of the argument was not equal to plus or minus infinity, and the 
imaginary part of the argument was not zero. 


WAIT statement cannot be executed because of restricted system facility. 
Greenwich mean time was not available for the RANDOM built-in function. 


An invalid seed value was detected in the RANDOM built-in function. The 
random number was set to -1. 


Local time was unavailable. 


Computational error; in MOD(x,y) built-in function the second argument was 
equal to zero. 


Computational error in ABS built-in function; real part of complex short 
floating-point argument was not a valid IEEE number. 


Computational error in ABS built-in function; real part of complex long 
floating-point argument was not a valid IEEE number. 


Computational error in ABS built-in function; real part of complex extended 
floating-point argument was not a valid IEEE number. 


Computational error in ABS built-in function; imaginary part of complex 
short floating-point argument was not a valid IEEE number. 


Computational error in ABS built-in function; imaginary part of complex long 
floating-point argument was not a valid IEEE number. 


Computational error in ABS built-in function; imaginary part of complex 
extended floating-point argument was not a valid IEEE number. 


Computational error in ABS built-in function; both parts of complex short 
floating-point argument were not valid IEEE numbers. 


Computational error in ABS built-in function; both parts of complex long 
floating-point argument were not valid IEEE numbers. 


Computational error in ABS built-in function; both parts of complex 
extended floating-point argument were not valid IEEE numbers. 


Computational error in ABS built-in function; integer argument is equal to 
(-2**31). 
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2161 
2162 
2163 
2164 
2165 
2166 

_ 2167 
2168 
2169 
2170 
2171 
2172 
2173 
2174 
2175 
2176 


2177 
2178 
2179 


2180 


2181 


2200 


Computational error in ABS built-in function; real short floating-point argu- 
ment was not a valid IEEE number. 


Computational error in ABS built-in function; real long floating-point argu- 
ment was not a valid IEEE number. 


Computational error in ABS built-in function; real extended floating-point 
argument was not a valid IEEE number. 


Computational error GAMMA or LOGGAMMA built-in function; real 
extended floating point argument is less than zero. 


Computational error GAMMA or LOGGAMMA built-in function; real short 
floating point argument is less than or equal to zero. 


Computational error GAMMA or LOGGAMMA built-in function; real long 
floating point argument is less than or equal to zero. 


Computational error GAMMA or LOGGAMMA built-in function; real 
extended floating point argument is equal to zero. 


Computational error GAMMA or LOGGAMMA built-in function; real short 
floating point argument is not a valid IEEE number. 


Computational error GAMMA or LOGGAMMA built-in function; real long 
floating point argument is not a valid IEEE number. 


Computational error GAMMA or LOGGAMMA built-in function; real 
extended floating point argument is not a valid IEEE number. 


Computational error in ERFC built-in function; real short floating-point argu- 
ment was greater than 9.19. 


Computational error in ERFC built-in function; real long floating-point argu- 
ment was greater than 26.54. 


Computational error in ERFC built-in function; real extended floating-point 
argument was greater than 106.53. 


Computational error in ERFC built-in function; real short floating-point argu- 
ment was not a valid IEEE number. 


Computational error in ERFC built-in function; real long floating-point argu- 
ment was not a valid IEEE number. 


Computational error in ERFC built-in function; real extended floating-point 
argument was not a valid IEEE number. 


Real short floating-point argument in ERF was not a valid IEEE number. 
Real long floating-point argument in ERF was not a valid IEEE number. 


Real extended floating-point argument in ERF was not a valid IEEE 
number. 


Computational error in SQRT; for complex short floating-point argument, 
real part was not equal to plus or minus infinity, and imaginary part was not 
equal to zero. 


Computational error in SQRT; for complex long floating-point argument, real 
part was not equal to plus or minus infinity, and imaginary part was not 
equal to zero. 


Computational error; during multiplication real part of first complex long 
floating-point argument was the only valid IEEE number. 
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2201 
2202 
2203 
2204 
2205 
2206 
2207 
2208 
2209 
2210 
2211 
2212 
2213 


2214 
2215 
2216 


2217 
2218 
2219 


2220 


2221 


Condition codes 


Computational error; during multiplication real part of first complex extended 
floating-point argument was the only valid IEEE number. 


Computational error; during multiplication the imaginary part of the first 
complex short floating-point argument was the only valid IEEE number. 


Computational error; during multiplication the imaginary part of the first 
complex long floating-point argument was the only valid IEEE number. 


Computational error; during multiplication the imaginary part of the first 
complex extended floating-point argument was the only valid IEEE number. 


Computational error; during multiplication the real part of the second 
complex short floating-point argument was the only valid IEEE number. 


Computational error; during multiplication the real part of the second 
complex long floating-point argument was the only valid IEEE number. 


Computational error; during multiplication the real part of the second 
complex extended floating-point argument was the only valid IEEE number. 


Computational error; during multiplication the imaginary part of the second 
complex short floating-point argument was the only valid IEEE number. 


Computational error; during multiplication the imaginary part of the second 
complex long floating-point argument was the only valid IEEE number. 


Computational error; during multiplication the imaginary part of the second 
complex extended floating-point argument was the only valid IEEE number. 


Computational error; during multiplication both parts of both complex short 
floating-point arguments were not valid IEEE numbers. 


Computational error; during multiplication both parts of both complex long 
floating-point arguments were not valid IEEE numbers. 


Computational error; during multiplication both parts of both complex 
extended floating-point arguments were not valid IEEE numbers. 


The real short floating-point argument for TRUNC was plus or minus infinity. 
The real long floating-point argument for TRUNC was plus or minus infinity. 
The real extended floating-point argument for TRUNC was plus or minus 
infinity. 

The real short floating-point argument for TRUNC was not a valid IEEE 
number. 


The real long floating-point argument for TRUNC was not a valid IEEE 
number. 


The real extended floating-point argument for TRUNC was not a valid IEEE 
number. 


Computational error; in MOD(x,y) built-in function real short floating-point 
arguments, the first argument was plus or minus infinity, or the second 
argument was plus or minus zero. 


Computational error; in MOD(x,y) built-in function real long floating-point 
arguments, the first argument was plus or minus infinity, or the second 
argument was plus or minus zero. 
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2222 


2223 
2224 
2225 
2226 

2227 
2228 
2229 
2230 
2231 
2250 
2251 
2252 
2253 
2254 

2255 
2256 
2257 
2258 
2259 


2260 


Computational error; in MOD(x,y) built-in function real extended floating- 
point arguments, the first argument was plus or minus infinity, or the second 
argument was plus or minus zero. 


Computational error; in MOD(x,y) built-in function real short floating-point 
arguments, the first argument was not a valid IEEE number. 


Computational error; in MOD(x,y) built-in function real long floating-point 
arguments, the first argument was not a valid IEEE number. 


Computational error; in MOD(x,y) built-in function real extended floating- © 
point arguments, the first argument was not a valid IEEE number. 


Computational error; in MOD(x,y) built-in function real short floating-point 
arguments, the second argument was not a valid IEEE number. 


Computational error; in MOD(x,y) built-in function real long floating-point 
arguments, the second argument was not a valid IEEE number. 


Computational error; in MOD(x,y) built-in function real extended floating- 
poini argumenis, tne second argument was noi a vaiid iEEE number. 


Computational error; in MOD(x,y) built-in function real short floating-point 
arguments, both arguments were not valid IEEE numbers 


Computational error; in MOD(x,y) built-in function real long floating-point 
arguments, both arguments were not valid IEEE numbers 


Computational error; in MOD(x,y) bulit-in function real extended floating- 
point arguments, both arguments were not valid IEEE numbers. 


Computational error; during multiplication for complex extended floating- 
point arguments plus or minus infinity was specified. 


Computational error; during multiplication the real part of the first complex 
short floating-point argument was not a valid IEEE number. 


Computational error; during multiplication the real part of the first complex 
long floating-point argument was noi a valid IEEE number. 


Computational error; during multiplication the real part of the first complex 
extended floating-point argument was not a valid IEEE number. 


Computational error; during multiplication the real part of the second 
complex short floating-point argument was not a valid IEEE number. 


Computational error; during multiplication the real part of the second 
complex long floating-point argument was not a valid IEEE number. 


Computational error; during multiplication the real part of the second 
complex extended floating-point argument was not a valid IEEE number. 


Computational error; during multiplication the imaginary part of the first 


complex short floating-point argument was not a valid IEEE number. 


Computational error; during multiplication the imaginary part of the first 
complex long floating-point argument was not a valid IEEE number. 


Computational error; during multiplication the imaginary part of the first 
complex extended floating-point argument was not a valid IEEE number. 


Computational error; during multiplication the imaginary part of the second 
complex short floating-point argument was not a valid IEEE number. 
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2261 


2262 


2263 


2264 


2265 


2266 


2267 


2268 


2269 


2270 


2271 


2272 


2273 


2274 


2275 


2276 


2277 


2278 


2279 


Condition codes 


Computational error; during multiplication the imaginary part of the second 
compiex jong floating-point argument was noi a valid IEEE number. 


Computational error; during multiplication the imaginary part of the second 
complex extended floating-point argument was not a valid IEEE number. 


Computational error; during multiplication both parts of first complex short 
floating-point arguments were not valid IEEE numbers. 


Computational error; during multiplication both parts of first complex long 
floating-point arguments were not valid IEEE numbers. 


Computational error; during multiplication both parts of first complex 
extended floating-point arguments were not valid IEEE numbers. 


Computational error; during multiplication both parts of second complex 
short floating-point arguments were not valid IEEE numbers. 


Computational error; during multiplication both parts of second complex 
long floating-point arguments were not valid IEEE numbers. 


Computational error; during multiplication both parts of second complex 
extended floating-point arguments were not valid IEEE numbers. 


Computational error; during multiplication real parts of both complex short 
floating-point arguments were not valid IEEE numbers. 


Computational error; during multiplication real parts of both complex long 
floating-point arguments were not valid IEEE numbers. 


Computational error; during multiplication real parts of both complex 
extended floating-point arguments were not valid IEEE numbers. 


Computational error; during multiplication imaginary parts of both complex 
short floating-point arguments were not valid IEEE numbers. 


Computational error; during multiplication imaginary parts of both complex 
long floating-point arguments were not valid IEEE numbers. 


Computational error; during multiplication imaginary parts of both complex 
extended floating-point arguments were not valid IEEE numbers. 


Computational error; during multiplication real part of first complex short 
floating-point argument and imaginary part of second complex short 
floating-point argument were not valid IEEE numbers. 


Computational error; during multiplication real part of first complex long 
floating-point argument and imaginary part of second complex long floating- 
point argument were not valid IEEE numbers. 


Computational error; during multiplication real part of first complex extended 
floating-point argument and imaginary part of second complex extended 
floating-point argument were not valid IEEE numbers. 


Computational error; during multiplication imaginary part of first complex 
short floating-point argument and real part of second complex short floating- 
point argument were not valid IEEE numbers. 


Computational error; during multiplication imaginary part of first complex 
long floating-point argument and real part of second complex long floating- 
point argument were not valid IEEE numbers. 
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358 


2280 


2281 


2300 


2301 


2302 


2303 


2304 


2305 


2306 


2307 


2308 


2309 


2310 


2311 


2312 


2313 


2314 


2315 


2316 


Computational error; during multiplication imaginary part of first complex 
extended floating-point argument and real part of second complex extended 
floating-point argument were not valid IEEE numbers. 


Computational error; during multiplication real part of first complex short 
floating-point argument was the only valid IEEE number. 


Computational error; during division real parts of both complex short 
floating-point arguments were not valid IEEE numbers. 


Computational error; during division real parts of both complex long floating- 
point arguments were not valid IEEE numbers. 


Computational error; during division real parts of both complex extended 
floating-point arguments were not valid IEEE numbers. 


Computational error; during division imaginary parts of both complex short 
floating-point arguments were not valid IEEE numbers. 


Computational error; during division imaginary parts of both complex long 
floating-point arguments were noi vaiid iEEE numbers. 

Computational error; during division imaginary parts of both complex 
extended floating-point arguments were not valid IEEE numbers. 


Computational error; during division real part of first complex short floating- 
point argument and imaginary part of second complex short floating-point 
argument were not valid IEEE numbers. 


Computational error; during division real part of first complex long floating- 
point argument and imaginary part of second complex long floating-point 
argument were not valid IEEE numbers. 


Computational error; during division real part of first complex extended 
floating-point argument and imaginary part of second complex extended 
floating-point argument were not valid IEEE numbers. 


Computational error; during division imaginary part of first complex short 
floating-point argument and real part of second complex short floating-point 
argument were not valid IEEE numbers. 


Computational error; during division imaginary part of first complex long 
floating-point argument and real part of second complex long floating-point 
argument were not valid IEEE numbers. 


Computational error; during division imaginary part of first complex 
extended floating-point argument and real part of second complex extended 
floating-point argument were not valid IEEE numbers. 


Computational error; during division real part of first complex short floating- 
point argument was the only valid IEEE number. 


Computational error; during division real part of first complex long floating- 
point argument was the only valid IEEE number. 


Computational error; during division real part of first complex extended 
floating-point argument was the only valid IEEE number. 


Computational error; during division imaginary part of first complex short 
floating-point argument was the only valid IEEE number. 


Computational error; during division imaginary part of first complex long 
floating-point argument was the only valid IEEE number. 
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2317 


2318 


2319 


2320 


2321 


2322 


2323 


2324 


2325 


2326 


2327 


2328 


2329 


2330 


2331 


2350 


2351 


2352 


2353 


2354 


2355 


2356 


Condition codes 


Computational error; during division imaginary part of first complex 
extended floating-point argument was the only valid EEE number. 


Computational error; during division real part of second complex short 
floating-point argument was the only valid IEEE number. 


Computational error; during division real part of second complex long 
floating-point argument was the only valid IEEE number. 


Computational error; during division real part of second complex extended 
floating-point argument was the only valid IEEE number. 


Computational error; during division imaginary part of second complex short 
floating-point argument was the only valid IEEE number. 


Computational error; during division imaginary part of second complex long 
floating-point argument was the only valid IEEE number. 


Computational error; during division imaginary part of second complex 
extended floating-point argument was the only valid IEEE number. 


Computational error; during division both parts of both complex short 
floating-point argument were not valid IEEE numbers. 


Computational error; during division both parts of both complex long 
floating-point argument were not valid IEEE numbers. 


Computational error; during division both parts of both complex extended 
floating-point argument were not valid IEEE numbers. 


Computational error; during multiplication complex short floating-point argu- 
ments equal to the limits. 


Computational error; during multiplication complex long floating-point argu- 
ments equal to the limits. 


Computational error; during multiplication complex extended floating-point 
arguments equal to the limits. 


Computational error; during multiplication for complex short floating-point 
arguments plus or minus infinity was specified. 


Computational error; during multiplication for complex long floating-point 
arguments plus or minus infinity was specified. 


Computational error; the first real long floating-point argument for SCALE 
was noi a valid IEEE number. 


Computational error; the first real extended floating-point argument for 
SCALE was not a valid IEEE number. 


X in CEIL(X) or FLOOR(X) was invalid for a real short floating-point argu- 
ment because the argument was plus or minus infinity. 


X in CEIL(X) or FLOOR(X) was invalid for a real long floating-point argu- 
ment because the argument was plus or minus infinity. 


X in CEIL(X) or FLOOR(X) was invalid for a real extended floating-point 
argument because the argument was plus or minus infinity. 


X in CEIL(X) or FLOOR(X) was invalid for a real short floating-point argu- 
ment because the argument was not a valid IEEE number. 


X in CEIL(X) or FLOOR(X) was invalid for a real long floating-point argu- 
ment because the argument was not a valid IEEE number. 
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2357 


2358 


2359 


2360 ~ 


2361 


2362 


2363 


2364 


2365 


2366 


2367 


2368 


2369 


2370 


2371 


2372 


2373 


2374 


2375 


2376 


2377 


2378 


X in CEIL(X) or FLOOR(X) was invalid for a real extended floating-point 
argument because the argument was not a valid IEEE number. 


Computational error; during division complex short floating-point arguments 
equal to the limits. 


Computational error; during division complex long floating-point arguments 
equal to the limits. 


Computational error; during division complex extended floating-point argu- 
ments equal to the limits. 


Computational error; during division for complex short floating-point argu- 
ments plus or minus infinity was specified. 


Computational error; during division for complex long floating-point argu- 
ments plus or minus infinity was specified. 


Computational error; during division for complex extended floating-point 
arguments plus or minus infinity was specified. 


Computational error; during division real part of first complex short floating- 
point argument was not a valid IEEE number. 


Computational error; during division real part of first complex long floating- 
point argument was not a valid IEEE number. 


Computational error; during division real part of first complex extended 
floating-point argument was not a valid IEEE number. 


Computational error; during division real part of second complex short 
floating-point argument was not a valid IEEE number. 


Computational error; during division real part of second complex long 
floating-point argument was not a valid IEEE number. 


Computational error; during division real part of second complex extended 
floating-point argument was not a valid IEEE number. 


Computational error; during division imaginary part of first complex short 
floating-point argument was not a valid IEEE number. 


Computational error; during division imaginary part of first complex long 
floating-point argument was not a valid IEEE number. 


Computational error; during division imaginary part of first complex 
extended floating-point argument was not a valid IEEE number. 


Computational error; during division imaginary part of second complex short 
floating-point argument was not a valid IEEE number. 


Computational error; during division imaginary part of second complex long 
floating-point argument was not a valid IEEE number. 


Computational error; during division imaginary part of second complex 
extended floating-point argument was not a valid IEEE number. 


Computational error; during division both parts of first complex short 
floating-point argument were not valid IEEE numbers. 


Computational error; during division both parts of first complex long floating- 
point argument were not valid IEEE numbers. 


Computational error; during division both parts of first complex extended 
floating-point argument were not valid IEEE numbers. 
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2379 


2380 


2381 


2403 


2404 


2407 


2408 


2409 


2410 


2411 


2412 


2413 


2414 


2415 


2416 


2417 


2418 


2419 


2420 


2421 


2422 


Condition codes 


Computational error; during division both parts of second complex short 
floating-point argument were not valid iEEE numbers. 


Computational error; during division both parts of second complex long 
floating-point argument were not valid IEEE numbers. 


Computational error; during division both parts of second complex extended 
floating-point argument were not valid IEEE numbers. 


Computational error; real extended floating point argument of GAMMA or 
LOGAMMA built-in function was less than or equal to minus zero. 


Computational error; real extended floating point argument of GAMMA or 
LOGAMMA built-in function was equal to zero. 


The calculated result of real short floating-point arguments for EXP over- 
flowed the output field. 


The calculated result of real long floating-point arguments for EXP over- 
flowed the output field. 


The calculated result of real extended floating-point arguments for EXP 
overflowed the output field. 


The calculated result of real short floating-point arguments for SCALE over- 
flowed the output field. 


The calculated result of real long floating-point arguments for SCALE over- 
flowed the output field. 


The calculated result of real extended floating-point arguments for SCALE 
overflowed the output field. 


Computational error; complex short floating-point argument in LOG, LOG2, 
or LOG10 built-in function was zero. 


Computational error; complex long floating-point argument in LOG, LOG2, 
or LOG10 built-in function was zero. 


Computational error; complex extended floating-point argument in LOG, 
LOG2, or LOG10 built-in function was zero. 


The calculated result of real short floating-point arguments for SINH or 
COSH calculated result overflowed output field 


The calculated result of real long floating-point arguments for SINH or 
COSH calculated result overflowed output field 


The calculated result of real extended floating-point arguments for SINH or 
COSH calculated result overflowed output field 


The calculated result of real short floating-point arguments for COTAN or 
COTAND calculated result overflowed output field 


The calculated result of real long floating-point arguments for COTAN or 
COTAND calculated result overflowed output field 


The calculated result of real extended floating-point arguments for COTAN 
or COTAND calculated result overflowed output field 


Computational error in SIN, COS, SIND, or COSD built-in function; for 
complex short floating-point argument the calculated result overflowed 
output field. 


Chapter 16. Conditions 361 


Condition codes 


362 


2423 


2424 


2430 


2431 


2450 


2451 


2452 


2453 


2454 


2455 


2456 


2457 


2458 


2459 


2460 


Computational error in SIN, COS, SIND, or COSD built-in function; for 
complex long floating-point argument the calculated result overflowed output 
field. 


Computational error in SIN, COS, SIND, or COSD built-in function; for 
complex extended floating-point argument the calculated result overflowed 
output field. 


Computational error in SIN, COS, SIND, or COSD built-in function; real 
short floating-point argument is equal to plus or minus infinity. 


Computational error in SIN, COS, SIND, or COSD built-in function; real long 
floating-point argument is equal to plus or minus infinity. 


Computational error in TAN or TAND built-in function; real short floating- 
point argument equal to plus or minus infinity. 


Computational error in TAN or TAND built-in function; real long floating- 
point argument equal to plus or minus infinity. 


Computational error in COTAN or COTAND built-in function; ee shor 
floating-point argument is equal to plus or minus zero, or pl minus 


infinity. 
Computational error in COTAN or COTAND built-in function; real long 


floating-point argument is equal to plus or minus zero, or plus or minus 
infinity. 


Computational error in COTAN or COTAND built-in function; real extended 
floating-point argument is equal to plus or minus zero. 


Computational error in EXPONENT built-in function; for complex long 
floating-point base with integer exponent, the calculated result was infinity. 


Computational error in EXPONENT built-in function; for complex extended 
floating-point base with integer exponent, the calculated result was infinity. 


Computational error in EXP built-in function; for complex short floating-point 
argument, the calculated result was infinity. 


Computational error in EXP built-in function; for complex long floating-point 
argument, the calculated result was infinity. 


Computational error in EXP built-in function; for complex extended floating- 
point argument, the calculated result was infinity. 


Computational error during division; for complex short floating-point argu- 
ment, the calculated result was infinity. 


Computational error during division; for complex long floating-point argu- 
ment, the calculated result was infinity. 


Computational error during division; for complex extended floating-point 
argument, the calculated result was infinity. 


Computational error in SQRT built-in function; for real short floating-point 
arguments, the ONCODE value was infinity. 


Computational error in SQRT built-in function; for real long floating-point 
arguments, the ONCODE value was infinity. 


Computational error in SQRT built-in function; for real extended floating- 
point arguments, the ONCODE value was infinity. 
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2461 


2462 


2463 


2464 


2465 


2466 


2467 


2468 


2469 


2470 


2471 


2472 


2473 


2474 


2475 


2476 


2477 


2478 


2479 


2480 


Condition codes 


Computational error in LOG built-in function; for real short floating-point 
argumenis, the caiculated result was infinity. 


Computational error in LOG built-in function; for real long floating-point 
arguments, the calculated result was infinity. 


Computational error in LOG built-in function; for real extended floating-point 
arguments, the calculated result was infinity. 


Computational error in ERFC built-in function; for real short floating-point 
arguments, the ONCODE value was infinity. 


Computational error in EFRC built-in function; for real long floating-point 
arguments, the ONCODE value was infinity. 


Computational error in EFRC built-in function; for real extended floating- 
point arguments, the ONCODE value was infinity. 


Computational error in ABS built-in function; for real short floating-point 
arguments, the ONCODE value was infinity. 


Computational error in ABS built-in function; for real long floating-point argu- 
ments, the ONCODE value was infinity. 


Computational error in ABS built-in function; for real extended floating-point 
arguments, the ONCODE value was infinity. 


Computational error in GAMMA or LOGGAMMA built-in function; for real 
short floating-point argument, the calculated result was infinity. 


Computational error in GAMMA or LOGGAMMA built-in function; for real 
long floating-point argument, the calculated result was infinity. 


Computational error in GAMMA or LOGGAMMA built-in function; for real 
extended floating-point argument, the calculated result was infinity. 


Computational error in EXPONENT built-in function; for real short floating- 
point base with real short floating-point exponent, the calculated result was 
infinity. 

Computational error in EXPONENT built-in function; for real long floating- 
point base with real long floating-point exponent, the calculated result was 
infinity. 

Computational error in EXPONENT built-in function; for real extended 
floating-point base with real extended floating-point exponent, the calculated 
result was infinity. 


Computational error in EXPONENT built-in function; for real short floating- 
point base with integer exponent, the calculated result was infinity. 


Computational error in EXPONENT built-in function; for real long floating- 
point base with integer exponent, the calculated result was infinity. 


Computational error in EXPONENT built-in function; for real extended 
floating-point base with integer exponent, the calculated result was infinity. 


Computational error in EXP built-in function; for real short floating-point 
argument, the calculated result was infinity. 


Computational error in EXP built-in function; for real long floating-point argu- 
ment, the calculated result was infinity. 
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2481 


2513 


2514 


2515 


2516 


2517 


2518 


2519 


2520 


2521 


2522 


2523 


2524 


2525 


2526 


2527 


2528 


2529 


2530 


2531 


Computational error in EXP built-in function; for real extended floating-point 
argument, the calculated result was infinity. 


Computational error in SQRT built-in function; for complex short floating- 
point arguments, the ONCODE value was infinity. 


Computational error in SQRT built-in function; for complex long floating- 
point arguments, the ONCODE value was infinity. 


Computational error in SQRT built-in function; for complex extended 
floating-point arguments, the ONCODE value was infinity. 


Computational error during multiplication; for complex short floating-point 
argument, the calculated result was infinity. 


Computational error during multiplication; for complex long floating-point 
argument, the calculated result was infinity. 


Computational error during multiplication; for complex extended floating- 
point argument, the calculated result was infinity. 


Computational error in LOG built-in function; for complex short floating-point 
arguments, the calculated result was infinity. 


Computational error in LOG built-in function; for complex long floating-point 
arguments, the calculated result was infinity. 


Computational error in LOG built-in function; for complex extended floating- 
point arguments, the calculated result was infinity. 


Computational error in EFRC built-in function; for complex short floating- 
point arguments, the ONCODE value was infinity. 


Computational error in EFRC built-in function; for complex long floating- 
point arguments, the ONCODE value was infinity. 


Computational error in EFRC built-in function; for complex extended 
floating-point arguments, the ONCODE value was infinity. 
Computational error in ABS built-in function; for complex short floating-point 


Computational error in ABS built-in function; for complex long floating-point 
arguments, the ONCODE value was infinity. 


Computational error in ABS built-in function; for complex extended floating- 
point arguments, the ONCODE value was infinity. 


Computational error in EXPONENT built-in function; for complex short 
floating-point base with complex short floating-point exponent, the calcu- 
lated result was infinity. 


Computational error in EXPONENT built-in function; for complex long 
floating-point base with complex long floating-point exponent, the calculated 
result was infinity. 


Computational error in EXPONENT built-in function; for complex extended 
floating-point base with complex extended floating-point exponent, the cal- 
culated result was infinity. 


Computational error in EXPONENT built-in function; for complex short 
floating-point base with integer exponent, the calculated result was infinity. 
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3000 


3006 
3009 


3010 


3011 


3012 
3013 


3014 
3015 
3016 


3017 


3797 
3798 
3799 


3800 
3808 
3809 
3810 
3901 


3904 


3906 
3907 


Condition codes 


* 


Field width, number of fractional digits, and number of significant digits (w,d, 
and s) specified for E-format item in edit-directed input/output statement do 
not allow transmission without loss of significant digits or sign. 


Picture description of target does not match noncharacter-string source. 


A mixed character string contained a shift-out, then ended before a shift-in 
was found. 


During processing of a mixed character constant, one of the following 
occurred: 


* A shift-in present in the SBCS portion. 

* A shift-out present in the graphic (double-byte) portion. (A shift-out 
cannot appear in either byte of a graphic character). 

* A shift-in present in the second byte of a graphic character. 


MPSTR built-in function contains an invalid character (or a null function 
string, or only blanks) in the expression that specifies processing rules. 
(Only V, v, S, s, and blank are valid characters). 


Retry for graphic conversion error not allowed. 


An assignment attempted to a graphic target with a length greater than 
16,383 characters (32,766 bytes). 


A graphic or mixed string did not conform to the continuation rules. 
A X or GX constant has an invalid number of digits. 


Improper use of graphic data in stream I/O. Graphic data can only be used 
as part of a variable name or string. 


Invalid graphic, mixed, or DBCS continuation when writing Stream I/O to a 
file containing fixed-length records. 


Attempt to convert to or from graphic data. 
ONCHAR or ONSOURCE pseudovariable used out of context. 


The source was not modified in the CONVERSION ON-unit. Retry was not 
attempted. An ON-unit was entered as a result of the CONVERSION con- 
dition being raised by an invalid character in the string being converted. 
The character was not corrected in an ON-unit using the ONSOURCE or 
ONCHAR pseudovariables. 


Length of data aggregate exceeds system limit of 2**24 bytes. 
Aggregate cannot be mapped in COBOL or FORTRAN. 

A data aggregate exceeded the maximum length. 

An array has an extent that exceeds the allowable maximum. 


Attempt to invoke process using a process variable that is already associ- 
ated with an active process. 


Event variable referenced as argument to COMPLETION pseudovariable 
while already in use for a DISPLAY statement. 


Assignment to an event variable that is already active. 


Attempt to associate an event variable that is already associated with an 
active process. 
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3909 


3910 


3911 


3912 


3913 
3914 


3915 


3920 
8091 
8092 
8093 
8094 
8095 
8096 
8097 
9002 
9003 
9050 
9200 
9201 
9250 
9251 
9252 
9253 
9999 


Attempt to create a subtask (using CALL statement) when insufficient main 
storage available. 


Attempt to attach a process (using CALL statement) when number of active 
processes was already at limit defined by ISASIZE parameter of EXEC 
statement. 


WAIT statement in ON-unit references an event variable already being 
waited for in process from which ON-unit was entered. 


Attempt to execute CALL with TASK option in block invoked while executing 
PUT FILE(SYSPRINT) statement. 


CALL statement with TASK option specifies an unknown entry point. 


Attempt to call FORTRAN or COBOL routines in two processes simultane- 
ously. 


Attempt to call a process when the multitasking library was not selected in 
the link-edit step. 


An out-of-storage abend occurred. 

Operation exception. 

Privileged operation exception. 

EXECUTE exception. 

Protection exception. 

Addressing exception. 

Specification exception. 

Data exception. 

Attempt to execute GO TO statement referencing label in an inactive block. 
Attempt to execute a GO TO statement to a non-existent label constant 
Program terminated by an abend. 

Program check in SORT/MERGE program. 

SORT not supported in CMS. 

Procedure to be fetched cannot be found. 

Permanent transmission error when fetching a procedure. 
FETCH/RELEASE not supported in CMS. 

PLITEST unavailable. 


A failure occurred in invocation of a Language Environment service. Use 
the ONFEEDBACK built-in function to determine the precise Language 
Environment error. 
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Chapter 17. Built-in functions, pseudovariables, and 
subroutines 


A large number of common tasks are available in the form of built-in functions, sub- — 
routines and pseudovariables. Using them lets you write less code more quickly 
with greater reliability. 


The built-in functions, subroutines, and pseudovariables are listed in alphabetic 
order later in this chapter. In general, each description has the following format: 


* A heading showing the syntax of the reference 

* A description of the value returned or, for a pseudovariable, the value set 
* A description of any arguments 

* Any other qualifications on using the function or pseudovariable. 


Note that the abbreviations for built-in functions have separate declarations (explicit 
or contextual) and name scopes. In the following example: 


dcl (Dim, Dimension). builtin; 


is not a multiple declaration, and 


dcl Binary file; 
X = Bin (var, 6,3); 


is valid even though Bin is an abbreviation of the Binary built-in function. 


Declaring built-in functions 


Built-in functions, pseudovariables, and subroutines can be contextually or explicitly 
declared. 


BUILTIN attribute 


The BUILTIN attribute specifies that the name is a built-in function, pseudovariable, 
or a subroutine. 


The syntax of the BUILTIN attribute is: 


SS SSS SS SS 


Built-in names can be used as programmer-defined names. BUILTIN can be 
declared for a built-in name in any block that has inherited, from a containing block, 
a programmer-defined declaration or use of the same name. The following exam- 
ples show built-in names with the BUILTIN attribute. 


© Copyright IBM Corp. 1992 371 


Invoking built-in functions and pseudovariables 


Example 1 
fj. A: procedure; 

declare Sqrt float binary; 
im 4 | A= Sars 


bl B: Begin; 
Declare Sqrt builtin; 
Z = Sqrt(P); 
end B; 


end A; 


Example 2 
A: procedure; 
Pf = Sqrt: proc(Param) returns(fixed(6,2)); 
declare Param fixed (12); 


end Sart; 
el x =-Sartcy)s 
| B: begin; 
declare Sqrt builtin; 
Z = Sqrt (P); 
end B; 


end A; 
In both examples: 
[i] Sart is a programmer-defined name. 
[2] The assignment to the variable X is a reference to the programmer-defined 
name Sart. 


BB] Sqrt is declared with the BUILTIN attribute so that any reference to Sqrt 
within B is recognized as a reference to the built-in function and not to the 
programmer-defined name Sart declared in 1. 

in Exampie 2, if the procedure Sart is externai, procedure A must deciare Sart 

explicitly as an entry name, and to specify the attributes of the values passed to 

and returned from this programmer-written function procedure. The declaration for 

Example 2 would be: 


dcl Sart entry (fixed (12)) 
returns (fixed(6,2)); 


Invoking built-in functions and pseudovariables 
The syntax used to invoke built-in functions and pseudovariables is as follows: 


Le —a.”t”*~<“—tiC—sSSSSSSC < 
(+) 


argument 
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Invoking built-in subroutines 


Invoking built-in subroutines 
The syntax used to invoke built-in subroutines is as follows: 


lis (rg ee < 
a L 


argument 





Specifying arguments for built-in functions 


Arguments, which can be expressions, are evaluated and converted to a data type 
suitable for the built-in function according to the rules for data conversion. 


Aggregate arguments 


All built-in functions and pseudovariables that can have arguments can have array 
arguments (if more than one is an array, the bounds must be identical). ADDR, 
ALLOCATION, CURRENTSIZE, SIZE, STRING, and the array-handling functions 
return an element value. All other functions return an array of values. Specifying 
an array argument is equivalent to placing the function reference or pseudovariable 
in a do-group where one or more arguments is a subscripted array reference that is 
modified by the control variable. 


For example: 


dc] A(2) char(2) varying; 
del B(2) char(2) 


MTEC SAB; GD"): 
dcl C(2) fixed bin 
i (ie eo ey ai 


A=substr(B,1,C); 
results in A(1) having the value A and A(2) having the value CD. 


The built-in functions and pseudovariables that can accept structure or union argu- 
ments are ADDR, ALLOCATION, CURRENTSIZE, SIZE, STRING, and UNSPEC. 


Null and optional arguments 


Some built-ins do not require arguments. You must either explicitly declare these 
with the BUILTIN attribute or contextually declare them by including a null argument 
list in the reference—for example, ONCHAR(). Otherwise, the name is not recog- 
nized as a built-in. 


Accuracy of mathematical functions 
The accuracy of a result is influenced by two factors: 


°* The accuracy of the argument 
* The accuracy of the algorithm. 
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Categories 


Most arguments contain errors. An error in a given argument can accumulate over 
several steps before the evaluation of a function. Even data fresh from input con- 
version can contain errors. The effect of argument error on the accuracy of a result 
depends entirely on the nature of the mathematical function, and not on the algo- 
rithm that computes the result. This book does not discuss argument errors of this 


type. 


Categories of built-in functions 
The following sections list built-in functions, subroutines, and pseudovariables. 


Only full function names are listed in these tables. Abbreviation that exist are pro- 
vided in the sections that describe each built-in function, subroutine, and 


pseudovariable. 


Arithmetic built-in functions 
The arithmetic built-in functions allow you to do the following: 


* Determine properties of arithmetic values. For example, the SIGN function indi- 
cates the sign of an arithmetic variable. 


* Perform routine arithmetic operations. 


Figure 54 lists the arithmetic built-in functions. 


Some of the arithmetic functions derive the data type of their results from one or 
more arguments. When the data types of the arguments differ, they are converted 
as described in Chapter 5, “Data conversion” on page 72. When a data attribute 
for the result cannot agree with that of the argument, the rules are given in the 
function description. 


Figure 54. Arithmetic built-in functions 


Function 
ABS 

CEIL 
COMPLEX 
CONJG 
FLOOR 
IMAG 
MAX 

MIN 

MOD 


RANDOM 
REM 
REAL 
ROUND 
SIGN 
TRUNC 
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Description 








Calculates the absolute value of a value 

Calculates the smallest integer value greater than or equal to a value 
Returns the complex number with given real and imaginary parts 
Returns the complex conjugate of a value 

Calculates the largest integer value less than or equal to a value 
Returns the imaginary part of a complex number 

Calculates the maximum of 2 or more values 

Calculates the minimum of 2 or more values 


Returns the modular equivalent of the remainder of one value divided 
by another 


Returns a pseudo-random value 

Calculates the remainder of one value divided by another 

Returns the real part of a complex number 

Rounds a value at a specified digit 

Returns a -1, O or 1 if a value is.negative, zero or positive respectively 


Calculates the nearest integer for value rounded towards zero. 


Array-handling 


Array-handling built-in functions 


The array-handling built-in functions operate on array arguments and return an 
element value. Any conversion of arguments required for these functions is noted 
in the function description. Figure 55 lists the array-handling built-in functions. 


Figure 55. Array-handling built-in functions 


Function Description 

ALL Calculates the bitwise “and” of all the elements of an array 
ANY Calculates the bitwise “or” of all the elements of an array 
DIMENSION Returns the number of elements in a dimension of an array 
HBOUND Returns the upper bound for a dimension of an array 
LBOUND Returns the lower bound for a dimension of an array 
PROD Calculates the product of all the elements of an array 

SUM Calculates the sum of all the elements of an array 


Condition-handling built-in functions 


The condition-handling built-in functions allow you to determine the cause of a con- 
dition that has occurred. 


Use of these functions is valid only within the scope of an ON-unit or dynamic 
descendant for the condition specific to the built-in function, or within an ON-unit or 
a dynamic descendant for the ERROR or FINISH condition when raised as an 
implicit action. All other uses are out of context. 


Figure 56. Condition-handling built-in functions 


Function Description 

DATAFIELD Returns the value of a string that raised the NAME condition 
ONCHAR Returns the value of a character that caused a conversion condition 
ONCODE Returns the condition code value 

ONCOUNT Returns the number of outstanding conditions 

ONFILE Returns the name of a file for which a condition is raised 


ONGSOURCE Returns a double-byte DBCS character string containing the DBCS 
character that caused the CONVERSION condition to be raised. 


ONKEY Returns the key of a record that raised a condition 
ONLOC Returns the name of the procedure in which a condition occurred 
ONSOURCE Returns the value of a string that caused a conversion condition 


Date/time built-in functions 


The date/time built-in functions return date and time information as a timestamp. 
Figure 57 lists the supported date/time built-in functions. 


Figure 57 (Page 1 of 2). Date/time built-in functions 
Function Description 
DATE Returns the current date in the pattern YYMMDD 
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Floating-point inquiry 


Figure 57 (Page 2 of 2). Date/time built-in functions 


Function 
DATETIME 


TIME 


Description 


Returns the current date and time in the pattern 
YYYYMMDDHHMiISS999 


Returns the current time in the pattern HHMMSS999 


Floating-point inquiry built-in functions 
The floating-point inquiry built-in functions return information about a the floating- 
point variable arguments that you specify. Figure 58 lists these built-in functions. 


Figure 58. Floating-point inquire built-in functions 


Function 
EPSILON 


PLACES 
RADIX 
TINY 


Description 

Returns the spacing around 1 
Retuims ine maximum vaiue for an exponent 
Returns the minimum value for an exponent 


Returns the largest positive finite value that a floating-point variable can 
hold 


Returns the model precision for a floating point value 
Returns the model base for a floating point value 


Returns the smallest positive value that a floating-point variable can 
hold 


Floating-point manipulation built-in functions 


The floating-point manipulation built-in functions perform mathematical operations 
on floating-point variables that you specify and return the result of the operation. 
Figure 59 lists the floating-point manipulation functions. 


Figure 59. Floating-point manipulation built-in functions 


Function 
EXPONENT 
SCALE 
PRED 
SUCC 


Description 

Returns the exponent part of a floating point value 

Multiplies a floating-point number by an integral power of 2 
Returns the next representable value before a floating-point value 


Returns the next representable value after a floating-point value 


Input/output built-in functions 


The input/output built-in functions allow you to determine the current state of a file. 
Figure 60 lists these functions. 


Figure 60 (Page 17 of 2). Input/output built-in functions 


Function 
COUNT 


ENDFILE 
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Description 


Returns the number of data items transmitted during the last GET or 
PUT . 


indicates if a file is open and end-of-file has been reached for it 


Integer manipulation 


Figure 60 (Page 2 of 2). Input/output built-in functions 


Function 
FILEOPEN 
LINENO 
PAGENO 
SAMEKEY 


Description 

Indicates if a file is open 

Returns the current line number associated with a print file 
Returns the current page number associated with a print file 


Indicates if a record is followed by another with the same key 


Integer manipulation built-in functions 


The integer manipulation built-in functions perform operations on integer variables 
and return the result of the operation. Figure 61 lists the integer manipulation func- 


tions. 


Figure 61. Integer manipulation built-in functions 


Function 
[AND 
IEOR 
lIOR 
LOWER2 
RAISE2 


Description 

Calculates the bitwise “and” of 2 fixed binary values 
Calculates the bitwise “exclusive-or’” of 2 fixed binary values 
Calculates the bitwise “or” of 2 fixed binary values 

Divides a fixed binary value by an integral power of 2 


Multiplies a fixed binary value by an integral power of 2 


Mathematical built-in functions 


All of these functions operate on floating-point values to produce a floating-point 
result. Any argument that is not floating-point is converted. The accuracy of these 
functions is discussed in “Accuracy of mathematical functions” on page 373. 
Figure 62 lists the mathematical built-in functions. 


Figure 62 (Page 1 of 2). Mathematical built-in functions 


Function 
ACOS 
ASIN 
ATAN 
ATAND 
ATANH 
COs 
COSD 
COSH 
COTAN 
COTAND 
ERF 
ERFC 
EXP 
GAMMA 


Description 

Calculates the arc cosine 

Calculates the arc sine 

Calculates the arc tangent 

Calculates the arc tangent in degrees 
Calculates the hyperbolic arc tangent 
Calculates the cosine 

Calculates the cosine for a value in degrees 
Calculates the hyperbolic cosine 

Calculates the cotangent 

Calculates the cotangent for a value in degrees 
Calculates the error function 

Calculates the complement of the error function 
Calculates e to a power 


Calculates the gamma function 
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Miscellaneous 


Figure 62 (Page 2 of 2). Mathematical built-in functions 


Function 
LOG 
LOGGAMMA 
LOG10 
LOG2 

SIN 

SIND 

SINH 

SQRT 

TAN 


TAND 
TANH 


Description 

Calculates the natural logarithm 
Calculates the log of the gamma function 
Calculates the base 10 logarithm 
Calculates the base 2 logarithm 
Calculates the sine 

Calculates the sine for a value in degrees 
Calculates the hyperbolic sine 

Calculates the square root 

Calculates the tangent 


Calculates the tangent for a value in degrees 


Calculates the hynerbolic tangent 


wee reeves 


Miscellaneous built-in functions 


The built-in functions that do not fit into any of the previous categories are those 
listed in Figure 63. 


Figure 63. Miscellaneous built-in functions 


Function 
COLLATE 
COMPARE 
HEX 
HEXIMAGE 


OMITTED 
PLIRETV 
STRING 


UNSPEC 
VALID 


Description 

Returns a character(256) string specifying the collating order 
Compares n bytes at two addresses 

Returns a character string that is the hex representation of a value 


Returns a character string that is the hex representation of a specified 
number of bytes at a given address 


Indicatac if a naramatar wac nat ciinnliad nn a reall 
Nee ates te DaraMmcick Was: nor supped Ona can 


Returns the PL/I return code value 


Returns a string that is the concatenation of all the elements of a string 
aggregate 


Returns a bit string that is the internal representation of a value 


Indicates if the contents of a variable are valid for its declaration 


Precision-handling built-in functions 


The precision-handling built-in functions allow you to manipulate variables with 
specified precisions, and they return the value resulting from the operation. 


Figure 64 (Page 1 of 2). Precision-handling built-in functions 


Function 
ADD' 
BINARY 
DECIMAL 
DIVIDE 
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Description 

Adds, with a specified precision, two values 
Converts a value to binary 

Converts a value to decimal 


Divides, with a specified precision, two values 


“ Pseudovariables 


Figure 64 (Page 2 of 2). Precision-handling built-in functions 


Function Description 

FIXED Converts a value to fixed 

FLOAT Converts a value to float 

MULTIPLY Multiplies, with a specified precision, two values 

SIGNED Converts a value to signed fixed binary 

PRECISION Converts a value to specified precision 

SUBTRACT Subtracts, with a specified precision, two values 

UNSIGNED Converts a value to unsigned fixed binary 
Pseudovariables 


Pseudovariables represent receiving fields. They cannot be nested, and can be 
used only on the left side of an assignment statement. For example, the following 
is invalid: 

unspec(substr(A,1,2)) = '00'B; 


The pseudovariables are: 


Figure 65. Built-in pseudovariables 


Function Description 

ENTRYADDR Sets an entry variable with the address of the entry to be invoked. 

IMAG Assigns the imaginary part of a complex number 

ONCHAR Seis the value of a character that caused a conversion condition 

ONGSOURCE Sets a double-byte DBCS character string containing the DBCS char- 
acter that caused the CONVERSION condition to be raised. 

ONSOURCE Sets the value of a string that caused a conversion condition 

REAL Assigns the real part of a complex number 

STRING Assigns a string that is the concatenation of all the elements of a string 
aggregate 

SUBSTR Assigns a substring of a string 

UNSPEC Assigns a bit string that is the internal representation of a value 


Storage control built-in functions 
The storage control built-in functions allow you to determine the storage require- 
ments and location of variables, to assign special values to area and locator vari- 
ables, to perform conversion between offset and pointer values, and to obtain the 
number of generations of a controlled variable. Figure 66 lists the storage control 
built-in functions. 


Figure 66 (Page 1 of 2). Storage control built-in functions 


Function Description 

ADDR Returns the address of a variable 

ALLOCATION Returns the current number of generations of a controlled variable 
BINARYVALUE Converts a pointer or offset to an integer 
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String-handling 


Figure 66 (Page 2 of 2). Storage control built-in functions 


Function Description P 
CURRENTSIZE Returns the current size of a variable 

EMPTY Returns an “empty” area 

ENTRYADDR Returns the address of the routine associated with an entry 
NULL Returns a null pointer value 

OFFSET Converts a pointer to an offset 

OFFSETADD Adds an integer to an offset 

OFFSETDIFF Subtracts two offsets 

OFFSETSUBTRACT Subtracts an integer from an offset 

OFFSETVALUE Converts an integer to an offset 

POINTER Converts an offset to a pointer 

POINTERADD Adds an integer to a pointer 

POINTERDIFF Subtracts two pointers 

POINTERSUBTRACT _ Subtracts an integer from a pointer 


POINTERVALUE 
SIZE 
SYSNULL 


Converts an integer to a pointer 
Returns the maximum size of a variable 


Returns a system null pointer value 


String-handling built-in functions 

The string-handling built-in functions simplify the processing of bit, character, and 
DBCS strings. The character- and bit-string arguments can be represented by an 
arithmetic expression that will be converted to string either according to data con- 
version rules or according to the rules given in the function description. 


Note: The functions CENTERLEFT, CENTERRIGHT, LEFT, RIGHT, TRANS- 
LATE, and TRIM do not support GRAPHIC data 


AR 


Figure 67 (Page 1 of 2). String-handling built-in functions 


Function 

BIT 

BOOL 
CENTERLEFT 
CENTERRIGHT 
CENTRELEFT 
CENTRERIGHT 
CHARACTER 
COPY 
GRAPHIC 

HIGH 


INDEX 
LEFT 


380 PL/I Package/2 Language Reference 


Description 

Converts a value to bit 

Performs boolean operation on 2 bit strings 

Returns a string with a value centered (to the left) in it 
Returns a string with a value centered (to the right) in it 
Returns a string with a value centered (to the left) in it 
Returns a string with a value centered (to the right) in it 
Converts a value to character 

Returns a string consisting of n copies of a string 
Converts a value to graphic 


Returns a string consisting of n copies of the highest character in the 
collating sequence 


Finds the location of one string within another 


Returns a string with a value left-justified in it 


Subroutines 


ABS 


Subroutines 


Figure 67 (Page 2 of 2). String-handling built-in functions 


Function 
LENGTH 
LOW 


MAXLENGTH 
MPSTR 


REPEAT 
REVERSE 
RIGHT 
SEARCH 


SEARCHR 


SUBSTR 
TRANSLATE 
TRIM 
VERIFY 


VERIFYR 


Description 
Returns the current length of a string 


Returns a string consisting of n copies of the lowest character in the 
collating sequence 


Returns the maximum length of a string 


Truncates a string at a logical boundary and returns a mixed character 
string. 


Returns a string consisting of n+1 copies of a string 
Returns a reversed image of a string 
Returns a string with a value right-justified in it 


Searches for the first occurrence of any one of the elements of a string 
within another string 


Searches for the first occurrence of any one of the elements of a string 
within another string but the search starts from the right 


Assigns a substring of a string . 
Translates a string based on two translation strings 
Trims specified characters from the left and right sides of a string 


Searches for first non-occurrence of any one of the elements of a string 
within another string 


Searches for first non-occurrence of any one of the elements of a string 
within another string but the search starts from the right 


Built-in subroutines perform miscellaneous operations that do not necessarily return 
a result as built-in functions do. Figure 68 lists the built-in subroutines. 


Figure 68. Built-in subroutines 


Function 
PLIDUMP 


PLIFILL 
PLIMOVE 
PLIRETC 


Description 


Dumps information about currently open files, the calling path to the 
current location, etc 


Fills n bytes at an address with a specified byte value 
Moves n bytes from one address to another 


Sets the PL/I return code value 


ABS returns the absolute value of x. It is the positive value of x. 


The syntax for ABS is: 


p>—ABS ( x) ————$$_$___________ 
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ACOS 


ACOS 


ADD 


x expression. 


The mode of the result is REAL. The result has the base, scale, and precision of x. 
The precision for FIXED COMPLEX is min(N,P+1). 


ACOS returns a real floating-point value that is an approximation of the inverse 
(arc) cosine in radians of x. 


The syntax for ACOS is: 


r>—ACOS( x) NN ——_¥_—_— od 


x real expression, where ABS(x) <= 1. 
The result is in the range: 
0< ACOS(x) < x 


and has the base and precision of x. 


ADD returns the sum of x and y with a precision specified by p and g. The base, 
scale, and mode of the result are determined by the rules for expression evaluation. 


The syntax for ADD is: 


ppe—ADD( X,Y, a <4 
| g | 


De ee ee 





x and y 
expressions. 

p restricted expression. It specifies the number of digits to be maintained 
throughout the operation. 

q restricted expression specifying the scaling factor of the result. For a 


fixed-point result, if g is omitted, a scaling factor of zero is the default. For 
a floating-point result, g must be omitted. 


ADD can be used for subtraction by prefixing a minus sign to the operand to be 
subtracted. 
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ADDR 


ADDR 


ADDR returns the pointer value that identifies the generation of x. 


The syntax for ADDR is: 


me—ADOR CX) Ar < 


x reference. It refers to a variable of any data type, data organization, align- 
ment, and storage class except: | 


A subscripted reference to a variable that is an unaligned fixed-length 
bit string 


A reference to a DEFINED or BASED variable or simple parameter, 
which is an unaligned fixed-length bit string 


A minor structure or union whose first base element is an unaligned 
fixed-length bit string (except where it is also the first element of the 
containing major structure or union) 


A major structure or union that has the DEFINED attribute or is a 
parameter, and that has an unaligned fixed-length bit string as its first 
element 


A reference that is not to connected storage. 


If x is a reference to: 


ALL 


An aggregate parameter, it must have the CONNECTED attribute. 
An aggregate, the returned value identifies the first element 


A component or cross section of an aggregate, the returned value 
takes into account subscripting and structure or union qualification 


A varying string, the returned value identifies the 2-byte prefix 
An area, the returned value identifies the control information 


A controlled variable that is not allocated in the current program, the 
null pointer value is returned 


A based variable, the result is the value of the pointer explicitly quali- 
fying x (if it appears), or associated with x in its declaration (if it 
exists), or a null pointer 


A parameter, and a dummy argument has been created, the returned 
value identifies the dummy argument. 


ALL returns a bit string in which each bit is 1 if the corresponding bit in each 
element of x exists and is 1. The length of the result is equal to that of the longest 


element. 
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ALLOCATION 


The syntax for ALL is: 


>>—ALL (x) NNN hh 


x array expression that must be either a NONVARYING BIT array reference 
or an expression that compares an array reference and an expression. 


ALLOCATION 


ALLOCATION returns a FIXED BIN(M,0) value specifying the number of gener- 
ations that can be accessed in the current program for x. 


The syntax for ALLOCATION is: 


>e—ALLOCAT 1ON( x) 


Abbreviation: ALLOCN 


x level-one unsubscripted controlled variable. 


If x is not allocated in the current program, the result is zero. 


ANY 


ANY returns a bit string in which each bit is 1 if the corresponding bit in any 
element of x exists and is 1. The length of the result is equal to that of the longest 
element. 


The syntax for ANY is: 


m ANY OX) $a $$ > 


x array expression that must be either a NONVARYING BIT array reference 
or an expression that compares an array reference and an expression. 


ASIN 


ASIN returns a real floating-point value that is an approximation of the inverse (arc) 
sine in radians of x. 


The syntax for ASIN is: 


| m»ASIN( x) lg | 
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ATAN 


x real expression, where ABS(x) <= 1. 
The result is in the range: 


— n/2 < ASIN(x) < n/2 


and has the base and precision of x. 





ATAN 
ATAN returns a floating-point value that is an approximation of the inverse (arc) 
tangent in radians of x or of a ratio x/y. 
The syntax for ATAN is: 
pie ere ) < 
x and y 
expressions. 
If x alone is specified, the result has the base and precision of x, and is in 
the range: 
— n/2 < ATAN(X) < 1/2 
If x and y are specified, each must be real. An error exists if x and y are 
both zero. The result for all other values of x and y has the precision of 
the longer argument, a base determined by the rules for expressions, and 
a value given by: 
ATAN(x/y) for y>0 
m/2 for y=0 and x>0 
-—n/2 for y=0 and x<0 
mt + ATAN(X/y) for y<O and x>=0 
—™+ATAN(X/y) for y<O and x<0 
ATAND 


ATAND returns a real floating-point value that is an approximation of the inverse 
(arc) tangent in degrees of x or of a ratio x/y. 


The syntax for ATAND is: 





>>—ATAND( oie 
J 
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ATANH 


ATANH 


BINARY 


x and y 
expressions. 


If x alone is specified it must be real. The result has the base and preci- 
sion of x, and is in the range: 


— 90 < ATAND(x) < 90 


If x and y are specified, each must be real. The value of the result is 
given by: 


(180/x)*ATAN(x,y) 


For argument requirements and attributes of the result see “ATAN” on page 385. 


ATANH returns a floating-point value that has the base, mode, and precision of x 


SS se ~~ ww ae ee oaks 


and is an approximation of the inverse (arc) hyperbolic tangent of x. 


The syntax for ATANH is: 


»>>—ATANH ( x) rp 


x expression. ABS(x)<1. 
The result has a value given by: 


LOG((1 + x/(1 — x))/2 


BINARY returns the binary value of x, with a precision specified by p and g. The 
result has the mode and scale of x. 


The syntax for BINARY is: 


G 


Abbreviation: BIN 





xX expression. 


p restricted expression. Specifies the number of digits to be maintained 
throughout the operation; it must not exceed the implementation limit. 


q restricted expression. It specifies the scaling factor of the result. Fora 
fixed-point result, if p is given and q is omitted, a scaling factor of zero is 
the default. For a floating-point result, q must be omitted. 
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BINARYVALUE 


BIT 


BOOL 


BINARYVALUE 


If both p and q are omitted, the precision of the result is determined from the rules 
for base conversion. 


BINARYVALUE returns a FIXED BIN(M,0) value that is the converted value of its 
pointer expression, x. 


The syntax for BINARYVALUE is: 


>>—B I NARY VALUE ( X)— AAA AA A A > 


Abbreviation: BINVALUE 


xX expression. 


BIT returns the bit value of x, with a length specified by y. 


The syntax for BIT is: 





ee 4 
JS 
x expression. 
y expression. If necessary, y is converted to a real fixed-point binary value. 


If yis omitted, the length is determined by the rules for type conversion. If 
y = 0, the result is the null bit string. y must not be negative. 


BOOL returns a bit string that is the result of the Boolean operation z, on x and y. 
The length of the result is equal to that of the longer operand, x or y. 


The syntax for BOOL is: 


p>——BOOL( X,Y, Z) >< 


x and y 
expressions. x and y are converted to bit strings, if necessary. If x and y 
are of different lengths, the shorter is padded on the right with zeros to 
match the longer. 
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CEIL 


CEIL 


CENTERLEFT 


z expression. zis converted to a bit string of length 4, if necessary. When 
a bit from x is matched with a bit from y, the corresponding bit of the result 
is specified by a selected bit of z, as follows: 


x y Result 

0 0 bit 1 of z 
0 1 bit 2 of z .. 
1 0 bit 3 of z 
1 1 bit 4 of z 


CEIL determines the smallest integer value greater than or equal to x, and assigns 
this value to the result. 


The syntax for CEIL is: 


a a a a i | 


DD 


X real expression. 


The result has the mode, base, scale, and precision of x, except when x is fixed- 
point with precision (p,q). The precision of the result is then given by: 


(min(N,max(p-qt1,1)),0) 


where N is the maximum number of digits allowed. 


CENTERLEFT returns a string that is the result of inserting string x in the center (or 
one position to the left of center) of a string with length y and padded on the left 
and on the right with the character z as needed. If zis omitted, a blank is used as 
the padding character. 


The syntax for CENTERLEFT is: 





>> Ee ee a ea 
LCENTRELEFT 2 


Abbreviation: CENTER 


x expression that is converted to character. 
y expression that is converted to FIXED BIN(M,0). 
z optional expression. If specified, z must be CHARACTER(1) NON- 


VARYING type. 
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CENTRELEFT 


Example 


dcl source char value('Feel the Power’); 
dcl target20 char(20); 
dcl target21 char(21); 


target20 = center (source, length(target20), '*'); 
/* '*kkFee] the Power***' - exactly centered */ 


target21 = center (source, length(target21), a 5 
/* '*kkFee] the Power****' - leaning left! */ 


CENTRELEFT 
Abbreviation: CENTRE 


CENTRELEFT is a synonym for CENTERLEFT. 


CENTERRIGHT 


CENTERRIGHT returns a string that is the result of inserting string x in the center 
(or one position to the right of center) of a string with length y and padded on the 
left and on the right with the character z as needed. If zis omitted, a blank is used 
as the padding character. 


The syntax for CENTERRIGHT is: 





eS oat ae. 
CENTRERIGHT. ws 


x expression that is converted to character. 
y expression that is converted to FIXED BIN(M,0). 
z optional expression. If specified, z must be CHARACTER(1) NON- 


VARYING type. 


Example 


dc! source char value('Feel the Power"); 
dc] target20 char(20); 
del target21 char(21); 


target20 = centerright (source, length(target20), '*'); 
/* '*kkFee] the Power***' - exactly centered */ 


target21 = centerright (source, length(target21), '*'); 
/* '*kkkFee] the Power***' - leaning right! */ 
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CENTRERIGHT 


CENTRERIGHT 


CHARACTER 





CENTRERIGHT is a synonym for CENTERRIGHT. 
CHARACTER returns the character value of x, with a length specified by y. CHAR- 
ACTER also supports conversion from graphic to character type. 
The syntax for CHARACTER is: 
ore sles 4 
Abbreviation: CHAR 
x expression. | 
xX must have a computational type. 
When x is nongraphic, CHARACTER returns x converted to character. 
When x is GRAPHIC, CHARACTER returns x converted to mixed char- 
acter. 
The values of x are not checked. 
y expression. If necessary, y is converted to a real fixed-point binary value. 


If yis omitted, the length is determined by the rules for type conversion. 
y cannot be negative. 
If y= 0, the result is the null character string. 


The following apply only when x is GRAPHIC: 


If y= 1, the result is a character string of 1 blank. 


If yis greater than the length needed to contain the character string, 
the result is padded with SBCS blanks. 


If yis less than the length needed to contain the character string, the 
result is truncated. The integrity is preserved by truncating after a 
graphic, and appending an SBCS blank if necessary, to complete the 
length of the string. 


Example 1: Conversion from graphic to character, where “y” is long enough to 
contain the result: 


dcl X graphic(6); 
dcl A char (14); 


A = char(X); 
For X with value: Intermediate Result: A is assigned: 
We beG DLE E Pe cea Cog OP en shy BeCa Dara k 
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COLLATE 


COMPARE 


COMPLEX 


COLLATE 


th, 599 


Example 2: Conversion from graphic to character, where “y” is too short: 


For X with value: Intermediate Result: A is assigned: 
Aub GvO.Es F JAB. GoD Er WByC. DED 


COLLATE returns a CHARACTER(256) string comprising the 256 possible 
CHARACTER(1) values one time each in the collating order. 


The syntax for COLLATE is: 


pee ee 
() 


COMPARE returns a FIXED BIN(M,0) string that is: 


° Zero, if the z bytes at the addresses x and y are identical 
* Negative, if the z bytes at x are less than those at y 
* Positive, if the z bytes at x are greater than those at y. 


The syntax for COMPARE is: 


bh COMPARE CK. 2) SS SSS 


x and y 
expressions. Both must have the POINTER or OFFSET type. If OFFSET, 
the expression must be declared with the AREA qualification. 


z expression that is converted to FIXED BIN(M,0). 


COMPLEX returns the complex value x + yl. 


The syntax for COMPLEX is: 


SS SS 


Abbreviation: CPLX 


x andy 
real expressions. 


if x and y differ in base, the decimal argument is converted to binary. If 
they differ in scale, the fixed-point argument is converted to floating-point. 
The result has the common base and scale. 
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CONJG 


The precision of the result, if fixed-point, is given by: 
(min(N,max(pl-ql,p2-q2)+max(ql,q2)),max(ql,q2)) 


where (p1,q1) and (p2,q2) are the precisions of x and y, respectively, and N is the 
maximum number of digits allowed. 


After any necessary conversions have been performed, if the arguments are 
floating-point, the result has the precision of the longer argument. 


CONJG 


CONJG returns the conjugate of x. the value of the expression with the sign of the 
imaginary part reversed. 


The syntax for CONJG is: 


| >>—CONIG (x) AA | 
x expression. 


If x is real, it is converted to complex. The result has the base, scale, 
mode, and precision of x. 


COPY 


COPY returns a string consisting of y concatenated copies of the string x. 


The syntax for COPY is: 


p>—COPY( x, y) A i 1 


x expression. 


X must have a computational type and should have a string type. If not, it 
is converted to character. 


y an integer expression with a nonnegative value. It specifies the number of 
repetitions. It must have a computational type and is converted to FIXED 
BIN(M,0). 


If yis zero, the result is a null string. 


For example: 
copy('Walla ',1) /* returns ‘Walla ' */ 
repeat('Walla ',1) /* returns 'Walla Walla ' */ 


repeat(x,n) is equivalent to copy(x,n+1). 
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cos 


COSD 


COSH 


COTAN 


co 


” 


COS returns a floating-point value that has the base, precision, and mode of x, and 
is an approximation of the cosine of x. 


The syntax for COS is: 


>>—C0S( x) 


+] 


expression with a value in radians. 


COSD returns a real floating-point value that has the base and precision of x, and 
is an approximation of the cosine of x. 


The syntax for COSD is: 


pe > 


ad 


real expression with a value in degrees. 


COSH returns a floating-point value that has the base, precision, and mode of x, 
and is an approximation of the hyperbolic cosine of x. 


The syntax for COSH is: 


»>—COSH( x) > 


* 


expression. 


COTAN returns a floating-point value that has the base, mode, and precision of x, 
and is an approximation of the cotangent of x. 


The syntax for COTAN is: 


ppe——COTAN( x )- A eee 


< 


expression. x must have a computational, arithmetic type. If x is numeric, 
it must be real. If x is not float, it is converted to float. 


The value of x is in radians. 
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COTAND 


COTAND 


COUNT 


CURRENTSIZE 


COTAND returns a floating-point value that is an approximation of the cotangent of 
x. It has the base, mode, and precision of x. 


The syntax for COTAND is: 


>> —COTAND( x) AAA A A > « 


x expression. x must have a computational, arithmetic type. If x is numeric, 
it must be real. If x is not float, it is converted to float. 


The value of x is in degrees. 


COUNT returns a real binary fixed-point value specifying the number of data items 
transmitted during the last GET or PUT operation on x. 


The syntax for COUNT is: 


>>—COUNT (x) AAA NNN 


x file-reference. The file must be open and have the STREAM attribute. 


The count of transmitted items for a GET or PUT operation on x is initialized to 
zero before the first data item is transmitted, and is incremented by one after the 
transmission of each data item in the list. If x is not open in the current program, a 
value of zero is returned. 


. 
r iy wm “~ 


If an ON-unit or procedure is entered during a GET or PUT ope: 
that ON-unit or procedure, a GET or PUT operation is executed for x, the value of 
COUNT is reset for the new operation. It is restored when the original GET or PUT 


is continued. 


+ cl oaithi 
auon, ana witnitt 


CURRENTSIZE returns a FIXED BIN(M,0) value giving the implementation-defined 
storage, in bytes, required by x. 


The syntax for CURRENTSIZE is: 


pe>—CURRENTSIZE CX) A S$ AA A > « 


x a variable of any data type, data organization, and storage class except: 


* A BASED, DEFINED, parameter, subscripted, or structure or union 
base-element variable that is an unaligned fixed-length bit string 
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CURRENTSTORAGE 


* A minor structure or union whose first or last base element is an una- 
ligned fixed-length bit string (except where it is also the first or last 
element of the containing major structure or union) 


* A major structure or union that has the BASED, DEFINED, or param- 
eter attribute, and which has an unaligned fixed-length bit string as its 
first or last element 


* A variable not in connected storage. 


The value returned by CURRENTSIZE(x) is defined as the number of bytes that 
would be transmitted in the following circumstances: 
declare F file record output 


environment(scalarvarying); 
write file(F) from(x); 


If x is a scalar varying-length string, the returned value includes the length-prefix of 
the string and the number of currently-used bytes. It does not include any unused 
bytes in the string. 


lf x is a scalar area, the returnec\value includes the area control bytes and the 
current extent of the area. It does not include any unused bytes at the end of the 
area. 


If x is an aggregate containing areas or varying-length strings, the returned value 
includes the area control bytes, the maximum sizes of the areas, the length prefixes 
of the strings, and the number of bytes in the maximum lengths of the strings. The 
exception to this rule is: — 


If x is a structure or union whose last element is a nondimensioned area, the 
returned value includes that area's control bytes and the current extent of that 
area. It does not include any unused bytes at the end of that area. 


For examples of the CURRENTSIZE built-in function, refer to the “SIZE” on 
page 436 and “MAXLENGTH’” on page 413. 


CURRENTSTORAGE 


DATAFIELD 


Abbreviation: CSTG 


CURRENTSTORAGE is a synonym for CURRENTSIZE. For more information, 
refer to “CURRENTSIZE” on page 394. 


DATAFIELD is in context in a NAME condition ON-unit (or any of its dynamic 
descendants). It returns a character string whose value is the contents of the field 
that raised the condition. It is also in context in an ON-unit (or any of its dynamic 
descendants) for an ERROR or FINISH condition raised as part of the implicit 
action for the NAME condition. 
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DATE 


The syntax for DATAFIELD is: 


Pe —— 
() 


If the string that raised the condition contains DBCS identifiers, GRAPHIC data, or 
mixed character data, DATAFIELD returns a mixed character string. 


If DATAFIELD is used out of context, a null string is returned. 


DATE 


DATE returns a character string timestamp (length 6) with the format YYMMDD, in 
which: 


YY is the current year 

MM is the current month 

DD is the current day 

The time zone and accuracy are system dependent. 


The syntax for DATE is: 


ey 8 or ee a se < 
() 


DATETIME returns a character string timestamp of today's data in the default 
format. 


DATETIME 


The syntax for DATETIME is: 


»>—DATET [MEA i? 7 


The format of the timestamp is 'YYYYMMDDHHMISS999’, in which 


YY is the current year. 


MM is the current month. 

DD is the current day. 

HH is the current hour. 

MI is the current minute. 

SS is the current second. 
999 is the current millisecond. 


If today's date is not available from the system, the ERROR condition is raised. 
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DECIMAL 








DECIMAL 

DECIMAL returns the decimal value of x, with a precision specified by p and q. 

The result has the mode and scale of x. 

The syntax for DECIMAL is: 

iia 7 a aan 
" Lyg 

Abbreviation: DEC 

x reference. 

p restricted expression specifying the number of digits to be maintained 
throughout the operation. 

q restricted expression specifying the scaling factor of the result. Fora 
fixed-point result, if p is given and q is omitted, a scaling factor of zero is 
assumed. For a floating-point result, gq must be omitted. 

If both p and g are omitted, the precision of the result is determined from the rules 

for base conversion. 

DIMENSION 

DIMENSION returns a FIXED BIN(M,0) value specifying the current extent of 

dimension y of x. 

The syntax for DIMENSION is: 

Ee ater er alee 4 

Abbreviation: DIM 

x array reference. x must not have less than y dimensions. 

y expression specifying a particular dimension of x. If necessary, y is con- 
verted to a FIXED BIN(M,0). y must be greater than or equal to 1. If yis 
not supplied, it defaults to 1. 

If y exceeds the number of dimensions of x, the DIMENSION function returns an 

undefined value. 

DIVIDE 


DIVIDE returns the quotient of x/y with a precision specified by p and q. The base, 
scale, and mode of the result follow the rules for expression evaluation. 
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EMPTY 


The syntax for DIVIDE is: 





< 


ie cs a Oa Fa 
»G 


x expression. 

y expression. If y= 0, the ZERODIVIDE condition is raised. 
restricted expression specifying the number of digits to be maintained 
throughout the operation. 

q restricted expression specifying the scaling factor of the result. Fora 


fixed-point result, if g is omitted, a scaling factor of zero is the default. For 
a floating-point result, g must be omitted. 


RAFT 
cCivIe~iY 
EMPTY returns an area of zero extent. It can be used to free all allocations in an 
area. 
The syntax for EMPTY is: 
eg ee ee es 
() 
The value of this function is assigned to an area variable when the variable is allo- 
cated. For example: 
declare A area, 
I based (P), 
J based (Q); 
allocate I in(A), J in (A); 
A = empty(); 
/* Equivalent to: free I in (A), J in (A); */ 
ENDFILE 


ENDFILE returns a '1'B when the end of the file is reached; '0'B if the end is not 
reached. If the file is not open, the ERROR condition is raised. 


The syntax for ENDFILE is: 


>>—ENDF ILE ( x) A A A NN > 


x file reference. 
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ENTRYADDR 


ENTRYADDR 


ENTRYADDR returns a pointer value that is the address of the first executed 
instruction if the entry x is invoked. The entry x must represent a non-nested pro- 
cedure. 


The syntax for ENTRYADDR is: 


pe—ENTRYADDR( xX) A AA > 


x entry reference. 


If x is a fetchable entry constant, it must be fetched before ENTRYADDR is exe- 
cuted. 


ENTRYADDR pseudovariable 


The ENTRYADDR pseudovariable initializes an entry variable, x, with the address 
of the entry to be invoked. 


The syntax for the ENTRYADDR pseudovariable is: 


pe—ENTRYADDR( x) A > 


x entry reference. 


Note: If the address supplied to the ENTRYADDR variable is the address of an 
internal procedure, the results are unpredictable. 


EPSILON 


EPSILON returns a floating-point value that is the spacing between x and the next 
positive number when x is 1. It has the base, mode, and precision of x. 


The syntax for EPSILON is: 


Beem EPS LON C1) ne 


x expression declared as REAL FLOAT. 


EPSILON(x) is a constant and may be used in restricted expressions. 


ERF 


ERF returns a real floating-point value that is an approximation of the error function 
of x. 
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ERFC 


The syntax for ERF is: 


p>p—ERF( x) 





< 


x 


real expression. 


The result has the base and precision of x, and a value given by: 


(2/functiom| (n) yf EXP(- (f))at 
0 


ERFC 


ERFC returns a real floating-point value that is an approximation of the complement 
of the error function of x. 


The syntax for ERFC is: 


mp e—EREC CX) > 


x 


real expression. 
The result has the base and precision of x, and a value given by: 


1 — ERF(x) 


EXP 


EXP returns a floating-point value that is an approximation of the base, e, of the 
naturai iogaritnm sysiem raised to the power x. 


The syntax for EXP is: 


pe—EXP (CX) $< > 


ba 


expression. 


The result has the base, mode, and precision of x. 


EXPONENT 
EXPONENT returns a FIXED BIN(M,0) value that is the exponent part of x. 


The syntax for EXPONENT is: 


>>—EXPONENT ( X) AA A 
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FILEOPEN 


FIXED 


FLOAT 


FILEOPEN | 


x expression. x must be declared as REAL FLOAT. 


EXPONENT(x) is not the “mathematical” exponent of x. 
If x = 0, EXPONENT(x) = 0. For other values of x, EXPONENT(x) is the unique 
number e such that: 


radix(x)'°~ ") < abs(x) < radix(x)® 


Consequently, EXPONENT(1e0) equals 1 and not 0. 


FILEOPEN returns '1'B if the file x is open; '0'B if the file is not open. 


The syntax for FILEOPEN is: 


pe—F TLEOPEN( x) A > « 


xX file reference. 


FIXED returns the fixed-point value of x, with a precision specified by p and g. The 
result has the base and mode of x. 


The syntax for FIXED is: 


i a ir < 
G 


xX expression. 





p restricted expression that specifies the total number of digits in the result. 
It must not exceed the implementation limit. 


q restricted expression that specifies the scaling factor of the result. If g is 
omitted, a scaling factor of zero is assumed. 


If both p and g are omitted, the precision of the result is determined from the rules 
for base conversion. 


FLOAT returns the approximate floating-point value of x, with a precision specified 
by p. The result has the base and mode of x. 


Chapter 17. Built-in functions, pseudovariables, and subroutines 401 


FLOOR 


The syntax for FLOAT is: 





ppe—FLOAT( al Dares 


x expression. 
p restricted expression that specifies the minimum number of digits in the 
result. 


If p is omitted, the precision of the result is determined from the rules for 
base conversion. 


FLOOR 
FLOOR determines the largest integer value less than or equal to x, and assigns 
this value to the result. 
The syntax for FLOOR is: 

>>—FLOOR( x) _——_—_——___ A $V ii >>? 

x real expression. 
The mode, base, scale and precision of the result match the argument. Except 
when x is fixed-point with precision (p,q), the precision of the result is given by: 
(min(N,max(p-qt1,1)),0) 
where N is the maximum number of digits allowed. 

PR ARARA A 

VUAINIIVIA 


GAMMA is an approximation of the gamma of x: 


oo 


gamma(x) -| (u*— "ye" du 
0 


GAMMA returns a floating-point value that has the base, mode, and precision of x. 


The syntax for GAMMA is: 


>> —GAMMA (x )—_——_- $a 


x expression. x must have a computational, arithmetic type. If x is numeric, 
it must be real and greater than zero. If x is not float, it will be converted 
to float. 
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GRAPHIC 


GRAPHIC 


GRAPHIC can be used to explicitly convert character (or mixed character) data to 
GRAPHIC data. All other data first converts to character, and then to the 
GRAPHIC data type. 


GRAPHIC returns the graphic value of x, with a length in graphic symbols specified 
by y. 


Characters convert to graphics. The content of x is checked for validity during con- 
version, using the same rules as for checking graphic and mixed character con- 
stants. 


The syntax for GRAPHIC is: 





p>—GRAPHIC( x ) 
y 


x expression. When x is GRAPHIC, it is subject to a length change, with 
applicable padding or truncation. When x is nongraphic, it is converted to 
character, if necessary. SBCS characters are converted to equivalent 
DBCS characters. 


y expression. If necessary, y is converted to a real fixed-point binary value. 
If yis omitted, the length is determined by the rules for type conversion. 


y must not be negative. 
lf y = 0, the result is the null graphic string. 


If yis greater than the length needed to contain the graphic string, the 
result is padded with graphic blanks. 


If yis less than the length needed to contain the graphic string, the result 
is truncated. 


Example 1: Conversion from CHARACTER to GRAPHIC, where the target is long 
enough to contain the result: 

dcl X char (11) varying; 

dcl A graphic (11); 

A = graphic(X,8); 


For X with values Intermediate Result A is assigned 

ABCDEFGHIJ (A.BeGD<EehsGsHs ded (AB. C.D. PoGshe be bab 
123 2.3 12030060. 000.0. 0.0 
123A.B.C ihatoaeAs B.C 1.2.3eA.BsC.b20.0.0.0 


where .b is a DBCS blank. 
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HBOUND 


Example 2: Conversion from CHARACTER to GRAPHIC, where the target is too 
short to contain the result. 


dcl X char (10) varying; 
dcl A graphic (8); 
A = graphic(X); 


For X with Values Intermediate Result A Is Assigned 
ABCDEFGHIJ A.B.C.D.E.F.G.H.1.d »~ 4A BeCeD EeroGsh 


HBOUND 
HBOUND returns a FIXED BIN(M,0) value specifying the current upper bound of 
dimension y of x. 
The syntax for HBOUND is: 
te ee ee ge ae ea ee ee ee 
| >>—HBOUND( x, y) A | 
x array reference. x must not have less than y dimensions. 
y expression specifying a particular dimension of x. If necessary, y is con- 
verted to FIXED BIN(M,0). y must be greater than or equal to 1. If yis not 
supplied, it defaults to 1. 
HEX 


HEX returns a character string that is the hexadecimal representation of the storage 
that contains x. 


Note: This function does not return an exact image of x in storage. If an exact 
image is required, use the HEXIMAGE built-in function. 


The syntax for HEX is: 





p>m>—HEX (x. ) 
ire 


HEX(x) returns a character string of length 2* size(x). 


HEX(x,z) returns a character string that contains x with the character z inserted 
between every set of eight characters in the output string. Its length is 
2x size(x) + (( size(x) — 1)/4). 


x expression that represents any variable. The whole number of bytes that 
contain x are converted to hexadecimal. 


z expression. If specified, z must result in CHARACTER(1) NONVARYING. 
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HEXIMAGE 


HEXIMAGE 


Example 


dc! Sweet char(5) init( Sweet’); 

dcl Sixteen fixed bin(31) init(16); 

dcl XSweet char(size( Sweet )*2+(size( Sweet )-1)/4); 

del XSixteen char(size(Sixteen)*2+(size(Sixteen)-1)/4); 


XSweet = hex(Sweet,'-'); 
/* '53776565-74' */ 


XSweet = heximage(addr( Sweet), length(Sweet),'-'); 
/* '53776565-74' */ 


XSixteen = hex(Sixteen,'-'); 
/* 'Q0000010' - bytes reversed */ 


XSixteen = heximage(addr(Sixteen),stg(Sixteen),'-'); 
/* '1Q000000' - bytes NOT reversed */ 


HEXIMAGE returns a character string that is the hexadecimal representation of the 
storage at a specified location. 


The syntax for HEXIMAGE is: 





»>—HEXIMAGE( p, ss paca 
+z 


HEXIMAGE(p,n) returns a character string that is the hexadecimal representation of 
n bytes of storage at location p. Its length is 2«n. 


HEXIMAGE(p,n,z) returns a character string that is the hexadecimal representation 
of n bytes of storage at location p with character z inserted between every set of 
eight characters in the output string. Its length is (2*n) + ((n—- 1)/4). 


p restricted expression that must have a locator type (POINTER or 
OFFSET). If p is OFFSET, it must have the AREA attribute. 

n expression. n must have a computational type and is converted to FIXED 
BIN(M,0). 

z ‘If specified, z must result in CHARACTER(1) NONVARYING. 


For examples of the HEXIMAGE built-in function, see “HEX” on page 404. 
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HIGH 


HIGH 


HUGE 


IAND 


HIGH returns a character string of length x, where each character is the highest 
character in the collating sequence (hexadecimal FF). 


The syntax for HIGH is: 


> >—H 1 GH x) > 


x expression. If necessary, x is converted to a positive real fixed-point 
binary value. If x = 0, the result is the null character string. 


; = 
HUGE returns a floating-point value that i 


vy 
It has the base, mode, and precision of x. 


The syntax for HUGE is: 


pe —HUGE (x) - A 


x expression. x must have the attributes REAL FLOAT. 


HUGE(x) is a constant and can be used in restricted expressions. 


IAND returns the logical AND of x and y. The result of IAND(x,y) for x and y fixed 
is the value that a REAL FIXED BIN(M,0) variable z would have after the assign- 
ment: 

unspec(z) = unspec(bin(x,31,0))&unspec(bin(y,31,0)) 


The syntax for IAND is: 


pp—TAND( X,Y) 


x expression. x must have a computational type and is converted to FIXED 
BIN(M,0). 
y expression. y must have a computational type and is converted to FIXED 


BIN(M,0). 
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IEOR 


IMAG 


IEOR 


IEOR returns the logical exclusive-OR of x and y. The result of ieor(x,y) for x and y 
fixed is the value that a FIXED BIN(M,0) variable z has after the assignment: 


unspec(z) = unspec(bin(x,31 ,0))unspec(bin(y,31 ,0)) 


The syntax for IEOR is: 


>>—IEOR( x, yy) NN > 


xX expression. x must have a computational type and is converted to FIXED 
BIN(M,0). 
y expression. y must have a computational type and is converted to FIXED 


- BIN(M,0O). 


IMAG returns the coefficient of the imaginary part of x. The mode of the result is 
real and has the base, scale, and precision of x. 


The syntax for IMAG is: 


>>—IMAG( x) NNN NN > 


x expression. If x is real, it is converted to complex. 


IMAG pseudovariable 


INDEX 


The IMAG pseudovariable assigns a real value or the real part of a complex value 
to the coefficient of the imaginary part of x. 


The syntax for IMAG is: 


p>—IMAG( X)-—NVN?NNNN > 


x complex reference. 


INDEX returns a real fixed-point binary value indicating the starting position within x 
of a substring identical to y. You can also specify the location within x where proc- 
essing begins. 
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IOR 


The syntax for INDEX is: 





cia ee eT 
or 


x string-expression to be searched. 
y string-expression to be searched for. 
n . n specifies the location within x at which to begin processing. It must have 


a computational type and is converted to FIXED BIN(M,0). 


If y does not occur in x, or if either x or y have zero length, the value zero is 
returned. 


If nis less than 1 or if nis greater than 1 + length(x), the STRINGRANGE condition 
will be raised, and the result will be 0. 


Example 
dc 


—_ 


greet char value ('Waheguru Ji Ka Khalsa, ' | 
‘Waheguru Ji Ka Fateh’); 


dcl pos fixed bin init(1); 


— 


pos = index (greet, ‘Ji’, pos); 
pe 10 a 


pos = index (greet, 'Ji', postl); 
[P33 rf 


pos = index (greet, ‘Ji', pos+l); 
=o i 


IOR returns the logical OR of x and y. The result of 1OR(x,y) for x and y fixed is 
the value that a REAL FIXED BIN(M,0) variable z would have after the assignment: 


unspec(z) = unspec(bin(x,31 ,0)) | unspec(bin(y,31,0)). 


The syntax for IOR is: 


p>—l0R( xX, yY) SS > 


x expression. x must have a computational type and is converted to FIXED 
BIN(M,0). 

y expression. y must have a computational type and is converted to FIXED 
BIN(M,0). . . 
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LBOUND 


LEFT 


LENGTH 


LBOUND 


LBOUND returns a FIXED BINARY (M,0) value specifying the current lower bound 
of dimension y of x. 


The syntax for LBOUND is: 


>>—LBOUND( x, y) —— 


< 


array reference. x must not have less than y dimensions. 


expression specifying a particular dimension of x. If necessary, y is con- 
verted to FIXED BIN(M,0). y must be greater than or equal to 1. If yis not 
supplied, it defaults to 1. 


< 


LEFT returns a string that is the result of inserting string x at the left end of a string 
with length n and padded on the right with the character z as needed. If zis 
omitted, a blank is used as the padding character. 


The syntax for LEFT is: 





< 


>pe—LEFT ( Xx, ar aa 
»Z 


xX expression. x must have a computational type and should have a char- 
acter type. If not, it is converted to CHARACTER. 

n expression. n must have a computational type and should have a char- 
acter type. If n does not have the attributes FIXED BIN(M,0), it is con- 
verted to them. 

z expression. If specified, z must result ina CHARACTER(1) NON- 
VARYING type. 

Example 


dc! source char value('One Hundred Dollars'); 
dcl target char(25); 


target = left (source, length(target), '*'); 
/* "One Hundred Dollars******' a 


LENGTH returns a real fixed-point binary value specifying the current length of x. 


The syntax for LENGTH is: 


| »e—LENGTH CX )-—-AA AA > | 
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LINENO 


x string-expression. If x is binary, it is converted to bit string; otherwise, any 
other conversion required is to character string. 


For examples of the LENGTH built-in function, refer to “SIZE” on page 436 and 
“MAXLENGTH” on page 413. 


LINENO 


LINENO returns a real fixed-point binary value specifying the current line number of 
x. 


The syntax for LINENO is: 


p> —LINENO( x) ______ —_ > 


x file-reference. 


The file must be open and have the PRINT attribute. If the file is not open or does 
not have the PRINT attribute, '0'B is returned. 


LOG 


LOG returns a floating-point value that is an approximation of the natural logarithm 
(the logarithm to the base e) of x. It has the base, mode, and precision of x. 


The syntax for LOG is: 


»>—L0G( x) ——ANANN a 


x expression. x must be greater than zero. 


LOGGAMMA 


LOGGAMMA returns a floating-point value that is an approximation of the log of 
gamma of x. 


GAMMA( = [ue 1) exp(u)du 
0 


It has the base, mode, and precision of x. 


The syntax for LOGGAMMA is: 


p>>—LOGGAMMA( xX) AA ANNA > 


x expression. x must have a computational type and should have an arith- 
metic type. If x is numeric, it must be real and greater than zero. The 
expression x is converted to FLOAT. 
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LOG2Z 


LOG10 


LOW 


LOWER2 


bs 


LOG2 


LOG2 returns a real floating-point value that is an approximation of the binary loga- 
rithm (the logarithm to the base 2) of x. It has the base and precision of x. 


The syntax for LOG2 is: 


Vv 
i 
r 
(on) 
G 
Ro 
oN 
x< 
A 


< 


real expression. The value of x must be greater than zero. 


LOG10 returns a real floating-point value that is an approximation of the common 
logarithm (the logarithm to the base 10) of x. It has the base and precision of x. 


The syntax for LOG10 is: 


>>—L.0G10( x) NAN NN > 


*< 


real expression. It must be greater than zero. 


LOW returns a character string of length x, where each character is the lowest 
character in the collating sequence (hexadecimal 00). 


The syntax for LOW is: 


LOW) A$ A ee 


expression. If necessary, x is converted to a positive real fixed-point 
binary value. If x = 0, the result is the null character string. 


LOWER2(x,n) returns the value of floor(x*(2-")). 


The syntax for LOWER2 is: 


>>—LOWER2( x, 2)———-ANANA.T NNN > 


Note: LOWER2(x,n) is equivalent to the assembler SRA(x,n). 


Chapter 17. Built-in functions, pseudovariables, and subroutines 411 


MAX 


x and n 
expressions. Both are converted to FIXED BIN(M,0O). 


The resuit is F'XED BIN(M,0). The result is undefined if n is negative or if nis 
greater than M. 


Examples 

lower2 (+6,1) /* Produces 3 */ 
lower2 (-6,1) /* Produces -3 */ 
lower2 (-7,1) /* Produces -4 */ 





MAX 
MAX returns the largest value from a set of two or more expressions. When used 
in restricted expressions, exactly two arguments must be specified. 
The syntax for MAX is: 
ae (oe < 
x andn expressions. 
All the arguments must be real. The result is real, with the common base and 
scale of the arguments. 
If the arguments are fixed-point with precisions: 
(pl sgl P2502 J yac ss (pn, qn) 
the precision of the result is given by: 
(min(N,max(pl-ql,p2-q2,...,pn-qn) + max(ql,q2,..., qn)),max(ql,q2,..., qn)) 
where N is the maximum number of digits allowed. 
If the arguments are floating point with precisions: 
DIG P27 03icecDN 
then the precision of the result is given by: 
max(pl,p2,p3,...pn) 
MAXEXP 


MAXEXP returns a FIXED BIN(M,0) value that is the maximum value that 
EXPONENT(x) could assume. 


The syntax for MAXEXP is: 


MRE EP CX) or 
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MAXLENGTH 


x expression. x must have the REAL and FLOAT attributes. 
MAXEXP(x) is a constant and can be used in restricted expressions. 
maxexp(x) = 128 for x float bin(p), p <= 21 

maxexp(x) = 1024 for x float bin(p), 21 < p <= 53 

maxexp(x) = 16384 for x float bin(p), 53 < p 

maxexp(x) = 128 for x float dec(p), p <= 61 

maxexp(x) = 1024 for x float dec(p), 6 < p <= 16 


oq 


maxexp(x) = 16384 for x float dec(p), 16 < p 


MAXLENGTH 


MAXLENGTH returns the maximum length of a string. 


The syntax for MAXLENGTH is: 


>>—MAXLENGTH( x )——A A '*n'“” 


xX expression. x must have a computational type and can have a string type. 
If not, it is converted to character. 


Example 
dcl scids char value('See you at SCIDS!'); 
dcl vscids char(20) varying init('See you at SCIDS!'); 
dcl len fixed bin(31); 
len = length (scids); /* 17 characters */ 
Jen = length (vscids); /* 17 characters */ 


Jen = maxlength (vscids); /* 20 characters */ 


len = length (len); {* 3) Dats * / 


len = maxlength (len); /* 31 bits */ 


For more examples, refer to “SIZE” on page 436. 


MIN 


MIN returns the smallest value from a set of two or more expressions. When used 
in restricted expressions, exactly two arguments must be specified. 


The syntax for MIN is: 


Spiny Ly 
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MINEXP 


xandn expressions. 


All the arguments must be real. The result is real with the common base and scale 
of the arguments. 


The precision of the result is the same as that described in “MAX” on page 412. 


MINEXP 
MINEXP returns a FIXED BIN(M,0) value that is the minimum value that 
EXPONENT(x) could assume. 
The syntax for MINEXP is: 
>>—MINEXP( x) ——_______________ lng 
x expression. x must have the REAL and FLOAT attributes 
MINEXP(x) is a constant and can be used in restricted expressions. 
minexp(x) = -125 for x float bin(p), p <= 21 
minexp(x) = -1021 for-x Tloat. bint p),; 21-< p-<=53 
minexp(x) = -16381 for x float bin(p), 53 < p 
minexp(x) = -125 for x float dec(p), p <= 6 
minexp(x) = -1021 for x Tloat: dec(p),.6<. p <= 16 
minexp(x) = -16381 for x float dec(p), 16 < p 
MOD 


MOD returns the smallest nonnegative value, R, such that: 
(x - R)/y =n 


where nis an integer value. That is, R is the smallest nonnegative value that must 
be subtracted from x to make it divisible by y. 


The syntax for MOD is: 


>>—M0D( x, Y)_ SS 


x real expression. 


y real expression. If y= 0, the ZERODIVIDE condition is raised. 


The result, R, is real with the common base and scale of the arguments. If the 
result is floating-point, the precision is the greater of those of x and y. If the result 
is fixed-point, the precision is given by: 

(min(N, p2-q2+max(ql,q2)),max(ql,q2)) 

where (p1,q1) and (p2,q2) are the precisions of x and y, respectively, and N is the 
maximum number of digits allowed. 
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MPSTR 


MPSTR 


If x and y are fixed-point with different scaling factors, the argument with the 
smaller scaling factor is converted to the larger scaling tactor before R is caicu- 
lated. If the conversion fails, the result is unpredictable. 


The following example contrasts the MOD and REM built-in functions. 
rem( +10, +8 ) = 2 


mod( +10, +8 ) = 2 
rem( +10, -8 ) = 2 
mod( +10, -8 ) =2 
rem( -10, +8 ) = -2 


mod( -10, +8 ) = 6 
rem( -10, -8 ) = -2 
mod( -10, -8 ) =6 


For information on the REM built-in function, see “REM” on page 430. 


MPSTR truncates a string at a logical boundary and returns a mixed character 
string. For example, it does not truncate a double-byte character between bytes. 
The length of the returned string is equal to the length of the expression x, or to the 
value specified by y. The processing of the string is determined by the rules 
selected by the expression r, as described below. 


The syntax for MPSTR is: 





>>—MPSTR(X, 2 ia 
Jy 


x expression that yields the character string result. The value of x cannot be 
GRAPHIC, and x is converted to character if necessary. 


r expression that yields a character result. The expression cannot be 
GRAPHIC and is converted to character if necessary. 


The expression r specifies the rules to be used for processing the string. 
The characters that can be used in rand the rules for them are as follows: 


Vorv_ Validates the mixed string x and returns a mixed string. 


Sors Removes any null DBCS strings and creates a new string. 
Returns a mixed string. 


If both V and S are specified, V takes precedence over S, regardless of 
the order in which they were specified. 


If S is specified without V, the string x is assumed to be a valid string. If 
the string is not valid, undefined results occur. 


y expression. If necessary, y is converted to a real fixed-point binary value. 
If yis omitted, the length is determined by the rules for type conversion. 
The value of y cannot be negative. If y= 0, the result is the null character 
string. If yis greater than the length needed to contain x, the result is 
padded with blanks. If y is less than the length needed to contain x, the 
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MULTIPLY 


MULTIPLY 


NULL 


OFFSET 


result is truncated by discarding excess characters from the right (if they 
are SBCS characters), or by discarding as many DBCS characters (2-byte 
pairs) as needed. 


MULTIPLY returns the product of x and y, with a precision specified by p and q. 
The base, scale, and mode of the result are determined by the rules for expression 
evaluation. 


The syntax for MULTIPLY is: 


pe>—MULTIPLY(X,y, Pe ell 





< 


expressions. 


p restricted expression that specifies the number of digits to be maintained 
throughout the operation. 
q restricted expression that specifies the scaling factor of the result. Fora 


fixed-point result, if g is omitted, a scaling factor of zero is assumed. For 
a floating-point result, g must be omitted. 


NULL returns the null pointer value. The null pointer value does not identify any 
generation of a variable. The null pointer value can be converted to OFFSET by 
assignment of the built-in function value to an offset variable. 


The syntax for NULL is: 


potas Se ee ee 
() 


OFFSET returns an offset value derived from a pointer reference x and relative to 
an area y. If x is the null pointer value, the null offset value is returned. 


The syntax for OFFSET is: 


pe—OFFSET (X,Y) KXAN N NN > —* 


x 


pointer reference. It must identify a generation of a based variable within 
the area y, or be the null pointer value. 
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OFFSETADD 


y area reference. 


If x is an element reference, y must be an element variable. 


OFFSETADD 
OFFSETADD returns the sum of the arguments. 


The syntax for OFFSETADD is: 


A Se 


x expression. x must be specified as OFFSET. 


y expression. y must have a computational type and is converted to FIXED 
BIN(M,0). 


OFFSETDIFF 


OFFSETDIFF returns a FIXED BIN(M,0) value that is the arithmetic difference 
between the arguments. 


The syntax for OFFSETDIFF is: 


>e—OFFSETDIFF( x, y)_- AA ____—_— 


x and y 
expressions. Both must be specified as OFFSET. 


OFFSETSUBTRACT 
OFFSETSUBTRACT is equivalent to OFFSETADD(x,-y). 


The syntax for OFFSETSUBTRACT is: 


>e>—OFFSETSUBTRACT (x, Y)_-A--_—_—_—_—_—_—_—____ 


x expressions. x must be specified as OFFSET. 
y expression. y must have a computational type and is converted to FIXED 
BIN(M,0) 
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OFFSETVALUE 


OFFSETVALUE 


OFFSETVALUE returns an offset value that is the converted value of x. 


The syntax for OFFSETVALUE is: 


bese ALLE) 


x expression. x must have a computational type and is converted to FIXED 
BIN(M,0). 


OMITTED 
OMITTED returns a BIT(1) value that is '1'B if the parameter named x was omitted 
in the invocation to its containing procedure 
The syntax for OMITTED is: 
>>—OMITTED( x) ——— >  _—_———_—__ > 
x level-one unscripted parameter with the BYADDR attribute. 
ONCHAR 


ONCHAR returns a 1-character string containing the character that caused the 
CONVERSION condition to be raised. It is in context in an ON-unit (or any of its 
dynamic descendants) for the CONVERSION condition or for the ERROR or 
FINISH condition raised as the implicit action for the CONVERSION condition. 


The syntax for ONCHAR is: 


a 


~~ 
Ww 
A 


If the ONCHAR built-in function is used out of context, a blank is returned. 
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ONCHAR pseudovariable 


ONCODE 


ONCOUNT 


The ONCHAR pseudovariable sets the current value of the ONCHAR built-in func- 
tion. The element value assigned to the pseudovariable is converted to a character 
value of length 1. The new character is used when the conversion is re-attempted. 
(See “CONVERSION condition” on page 315.) 


The syntax for ONCHAR pseudovariable is: 


i 


The pseudovariable must not be used out of context. 


The ONCODE built-in function provides a fixed-point binary value that depends on 
the cause of the last condition. ONCODE can be used to distinguish between the 
various circumstances that raise a particular condition (for instance, the ERROR 
condition). For codes corresponding to the conditions and errors detected, see the 
specific condition in Chapter 16, “Conditions” on page 312. 


ONCODE returns a real fixed-point binary value that is the condition code. It is in 
context in any ON-unit or its dynamic descendant. All condition codes are defined 
in Chapter 16, “Conditions” on page 312. 


The syntax for ONCODE is: 


a 
() 


lf ONCODE is used out of context, zero is returned. 


ONCOUNT returns a FIXED BIN(M,0) value specifying the number of conditions 
that remain to be handled when an ON-unit is entered. Multiple conditions are dis- 
cussed under “Multiple conditions” on page 309. It is in context in any ON-unit, or 
any dynamic descendant of an ON-unit. 


The syntax for ONCOUNT is: 


La 
() 


lf ONCOUNT is used out of context, zero is returned. 
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ONFILE 


ONFILE returns a character string whose value is the name of the file for which an 
input/output or CONVERSION condition is raised. If the name is a DBCS name, it 
will be returned as a mixed character string. It is in context in the following circum- 
stances: 


* In an ON-unit, or any of its dynamic descendants 
® For any input/output or CONVERSION condition 


°® For the ERROR or FINISH condition raised as implicit action for an input/output 
or the CONVERSION condition. 


The syntax for ONFILE is: 


a ee 
() 


a i ne ee | 


If ONFILE is used out of context, a null string is returned. 


ONGSOURCE 


ONGSOURCE returns a graphic string containing the DBCS character that caused 
the CONVERSION condition to be raised. It is in context in an ON-unit (or any of 
its dynamic descendants) for the CONVERSION condition or for the ERROR or 
FINISH condition raised as the implicit action for the CONVERSION condition. 


The syntax for ONGSOURCE is: 


Re TN ee oh ee Ss ee a ee 
() 


If the ONGSOURCE built-in function is used out of context, a DBCS blank is 
returned. 





ONGSOURCE pseudovariable 


The ONGSOURCE pseudovariable sets the current value of the ONGSOURCE 
built-in function. The element value assigned to the pseudovariable is converted 
graphic. The string is used when the conversion is re-attempted. (See “CONVER- 
SION condition” on page 315.) 


The syntax for ONGSOURCE pseudovariable is: 


yn ee 
() 


The pseudovariable must not be used out of context. 
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ONKEY 


ONLOC 


ONKEY 


ONKEY returns a character string whose value is the key of the record that raised 
an input/output condition. For indexed files, if the key is GRAPHIC, the string is 
returned as a mixed character string. ONKEY is in context for the following: 


°* An ON-unit, or any of its dynamic descendants 
° Any input/output condition, except ENDFILE 


* The ERROR or FINISH condition raised as implicit action for an input/output 
condition. 


ONKEY is always set for operations on a KEYED file, even if the statement that 
raised the condition has not specified the KEY, KEYTO, or KEYFROM options. 


The syntax for ONKEY is: 


() 


The result of specifying ONKEY is: 


® For any input/output condition (other than ENDFILE), or for the ERROR or 
FINISH condition raised as implicit action for these conditions, the result is the 
value of the recorded key from the I/O statement causing the error. 


* For relative data sets, the result is a character string representation of the rela- 
tive record number. If the key was incorrectly specified, the result is the last 8 
characters of the source key. If the source key is less than 8 characters, it is 
padded on the right with blanks to make it 8 characters. If the key was cor- 
rectly specified, the character string consists of the relative record number in 
character form padded on the left with blanks, if necessary. 


° For a REWRITE statement that attempts to write an updated record on to an 
indexed data set when the key of the updated record differs from that of the 
input record, the result is the value of the embedded key of the input record. 


If ONKEY is used out of context, a null string is returned. 


ONLOC returns a character string whose value is the name of the entry-point used 
for the current invocation of the procedure in which a condition was raised. 


ONLOC always returns the first name of a multiple label specification, regardless of 
which name appears in the CALL or GOTO statement. 


If the name is a DBCS name, it is returned as a mixed character string. It is in 
context in any ON-unit, or in any of its dynamic descendants. 
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ONSOURCE 


The syntax for ONLOC is: 


Sr a < 
() 
(ee | 


If ONLOC is used out of context, a null string is returned. 


ONSOURCE returns a character string whose value is the contents of the field that 
was being processed when the CONVERSION condition was raised. It is in 
context in an ON-unit, or any of its dynamic descendants, for the CONVERSION 
condition or for the ERROR or FINISH condition raised as the implicit action for the 
CONVERSION condition. 


If ONSOURCE is used out of context, a null string is returned. 


ONSOURCE pseudovariable 


The pseudovariable sets the current value of the ONSOURCE built-in function. The 
element value assigned to the pseudovariable is converted to a character string 
and, if necessary, is padded on the right with blanks or truncated to match the 
length of the field that raised the CONVERSION condition. The string is used when 
the conversion is re-attempted. For information about conversion refer to “CON- 
VERSION condition” on page 315. 


The syntax for ONSOURCE pseudovariable is: 


= 
() 


When conversion is re-attempted, the string assigned to the pseudovariable is proc- 
essed as a single data item. For this reason, the error correction process must not 
assign a string containing more than one data item when the conversion occurs 
during the execution of a GET LIST or GET DATA statement. The presence of 
blanks or commas in the string could raise CONVERSION again. 


The pseudovariable must not be used out of context. 
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PAGENC 


PLACES 


PLIDUMP 


PAGENO 


PAGENO returns a FIXED BIN(M,0) value that is the current page number associ- 
ated with file x. 


The syntax for PAGENO is: 


»>—PAGENO( X) 


x an open PRINT file. 
If the file is not a PRINT file, the ERROR condition is raised. 


PLACES returns a FIXED BIN(M,0) value that is the model-precision used to repre- 
sent the floating point expression x. 


The syntax for PLACES is: 


pp——PLACES ( X) $$ $$ > 4 


x expression. x must be declared REAL FLOAT. 
PLACES(x) is a constant and can be used in restricted expressions. 
places(x) = 24 for x float bin(p), p <= 2l 

places(x) = 53 for x float bin(p), 21 < p = 53 
places(x) = 64 for x float bin(p), 53 < p 

places(x) = 24 for x float dec(p), p = 61 

places(x) = 53 for x float dec(p), 6 < p <= 16 

places(x) = 64 for x float dec(p), 16 < p 


This built-in subroutine allows you to obtain a formatted dump of selected parts of 
storage used by your program. 


The syntax for PLIDUMP is: 


»>—PLIDUMP( OU ga Oe ee < 
,argument. 


For more information about using PLIDUMP, see PL/I Package/2 Programming 
Guide. 
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PLIFILL 


PLIFILL 


PLIMOVE 


PLIFILL moves z copies of the byte y to the location x without any conversions, 
padding, or truncation. 


The syntax for PLIFILL is: 


DD —PLI FILL X, Y5, 2 mem rn 


x expression. x must be declared POINTER or OFFSET. If it is OFFSET, x 
must be declared with the AREA attribute. 

y must be declared CHARACTER(1) NONVARYING. 

z expression that is converted to FIXED BIN(M,0). 

Exainpie 

del 1 strl, 

2b fixed bin(31), 
2 pointer, 


2 * union, 


C 
* 

3 d_ char(4), 
3 e fixed bin(31), 
3 * 


4.*--char(3), 
4 f fixed bin(8) unsigned, 
2 * char(0) 
initial call plifill( addr(str1), 'OOQ'x, stg(strl) ); 


PLIMOVE moves z storage units (bytes) from location y to location x, without any 
conversions, padding, or truncation. 


The syntax for PLIMOVE is: 


>e—PLIMOVE( X,Y, 2) $$ A > 


x andy 
expressions declared as POINTER or OFFSET. If the type is OFFSET, x 
or y must be declared with the AREA attribute. 


z expression. z must have a computational type and is converted to FIXED 
BIN(M,0). 


Storage at locations x and y is assumed to be unique. If storage overlaps, unpre- 
dictable results can occur. 
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PLIRETC 


PLIRETV 


POINTER 


PLIRETC 


Example 


del a. striy 
2b fixed bin(31), 
2c pointer, 
2 Union, 
3d char(4), 
3 e fixed bin(31), 
Ce 
4 * char(3), 
4 f fixed bin(8) unsigned, 
2 * char(0); 
dcl 1 template nonasgn static, 
2 * fixed bin(31) init(200), 


2 * pointer init(null()), 
2 *-char(4) init¢'"), 
2 * char(0); 


call plimove(addr(str1l), addr(template), stg(str1)); 


This built-in subroutine allows you to set a return code that can be examined by the 
program that invoked this PL/I program or by another PL/I procedure via the 
PLIRETV built-in function. 


The syntax for PLIRETC is: 


pe—PLIRETC( xX) S$ > 


x an expression yielding a FIXED BINARY(M,0) return code. 


PLIRETV returns a FIXED BIN(M,0) value that is the PL/I return code. 


The syntax for PLIRETV is: 


Pe ee < 
() 


The value of the PL/I return code is the most recent value specified by a CALL 
PLIRETC statement. 


POINTER returns a pointer value that identifies the generation specified by an 
offset reference x, in an area specified by y. If x is the null offset value, the null 
pointer value is returned. 
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POINTERADD 


POINTERADD 


POINTERDIFF 


The syntax for POINTER is: 


pe—POINTER( X, Y)_-- > 


Abbreviation: PTR 


x offset reference. It can be the null offset value. If it is not, x must identify 
a generation of a based variable, but not necessarily in y. If it is not in y, 
the generation must be equivalent to a generation in y. 


y area reference. 


Generations of based variables in different areas are equivalent if, up to the allo- 
cation of the latest generation, the variables have been allocated and freed the 
same number of times as each other. 


POINTERADD returns a pointer value that is the sum of its arguments. 


The syntax for POINTERADD is: 


>>—POINTERADD( X, Y) > < 


Abbreviation: PTRADD 
x pointer expression. 


y expression that must have a computational type and is converted to 
FIXED BIN(M,O). 


POINTERADD can be used as a locator for a based variable. 


POINTERADD can be used for subtraction by prefixing the operand to be sub- 
tracted with a minus sign. 


POINTERDIFF returns a FIXED BIN(M,0) result that is the difference between the 
two pointers x and y. 


The syntax for POINTERDIFF is: 


p>>—POINTERDIFF CX, y)_-_- $$ > A  —  ——__—_——_——_— > 4 


x and y 
expressions declared as POINTER. 
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POINTERSUBTRACT 


POINTERSUBTRACT 


POINTERSUBTRACT is equivalent to POINTERADD(x,-y). 


The syntax for POINTERSUBTRACT is: 


p> —POINTERSUBTRACT (X,Y) A ___—_ > 


x must be a pointer expression. 


y expression that must have a computational type and is converted to 
FIXED BIN(M,0O). 


POINTERVALUE 


PRECISION 


POINTERVALUE returns a pointer value that is the converted value of x. 


The syntax for POINTERVALUE is: 


p>—POINTERVALUE ( Xx) $$ > 4 


Abbreviation: PTRVALUE 


x expression that must have a computational type and is converted to 
FIXED BIN(M,0O). 


POINTERVALUE(x) can be used to initialize static pointer variables if x is a con- 
stant. 


PRECISION returns the value of x, with a precision specified by p and g. The 
base, mode, and scale of the returned value are the same as that of x. 


The syntax for PRECISION is: 


pe>—PRECISIONC(X, i 


Abbreviation: PREC 





< 


xX expression. 

p restricted expression. p specifies the number of digits that the value of the 
expression x is to have after conversion. 

q restricted expression. It specifies the scaling factor of the result. Fora 


fixed-point result, if g is omitted, a scaling factor of zero is assumed. For 
a floating-point result, g must be omitted. 
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PRED 


PRED 


PRED returns a floating-point value that is the biggest representable number 
smaller than x. It has the base, mode, and precision of x. OVERFLOW will be 
raised if there is no such number. 


The syntax for PRED is: 


me—PRE D(X) A > 


x expression declared REAL FLOAT. ° 


PROD 


The syntax for PROD is: 


pe—PROD( x) -— NNN —___———__ > « 


Fad 


array reference. If the elements of x are strings, they are converted to 
fixed-point integer values. 


If the elements of x are not fixed-point integer values or strings, they are 
converted to floating-point and the result is floating-point. 


The result has the precision of x, except that the result for fixed-point integer values 
and strings is fixed-point with precision (n,0), where nis the maximum number of 
digits allowed. The base and mode match the converted argument x. 


RADIX 
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RADIX returns a FIXED BIN(M,O) value that is the model-base used to represent 
the floating point expression x. 


The syntax for RADIX is: 


ST eT 


x expression declared REAL FLOAT. 


RADIX(x) is 2 and can be used in restricted expressions. 
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RAISE2 


RANDOM 


REAL 


RAISE2 


RAISE2(x,n) returns the value of xx(2”). 


The syntax for RAISE2 is: 


p>—RAISE2( x, 2.) -—P--ANAN)>Y>NN ————_—__> 4 


Note: RAISE2(x,n) is equivalent to the assembler SLA(x,n). 


x andn 
expressions that must have a computational type and is converted to 
FIXED BIN(M,0O). 


The result has the type FIXED BIN(M,0). It is undefined if n is negative or if nis 
greater than M. . 


Example 
raise2(6,1) /* produces 12 */ 


RANDOM returns a FLOAT BIN(53) random number generated using x as the 
given seed. If x is omitted, the random number generated is based on the seed 
provided by the last RANDOM invocation with a seed, or on a default initial seed of 
1 if RANDOM has not previously been invoked with a seed. 


The syntax for RANDOM is: 


a a aaa < 
(x) 


x expression. x must have a computational type and should have an arith- 
metic type. If x is numeric, it must be real. If x is not specified FIXED 
BIN(M,0), it is converted. 


REAL returns the real part of x. The result has the base, scale, and precision of x. 


The syntax for REAL is: 


me—REALC X )-—- > 


x expression. If x is real, it is converted to complex. 
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REAL 


REA 


REM 


pseudovariable 


L pseudovariable 


The pseudovariable assigns a real value or the real part of a complex value to the 
real part of x. 


The syntax for REAL pseudovariable is: 


>&®—REAL ( Xx) AAA eee 


x complex reference. 


REM returns the remainder of x divided by y. This can be calculated by: 
xX — yxtrunc(x/y) 


The syntax for REM is: 


>>—REMCX, Y)_—_—A- NN i i > 


x and y 
expressions. x and y must be computational and can be arithmetic. 


For examples that contrast the REM and MOD built-in functions, refer to “MOD” on 
page 414. 


REPEAT 
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REPEAT returns a bit or character string consisting of x concatenated to itself the 
number of times specified by y. That is, there will be (y + 1) occurrences of x. 


The syntax for REPEAT is: 


p>e—REPEAT ( X,Y) AN  —_—_- > 


x bit- or character-expression to be repeated. If x is arithmetic, the following 
conversions occur: 


e If it is binary, x is converted to bit string 
e If it is decimal, x is converted to character string. 


y expression. If necessary, y is converted to a real fixed-point binary value. 


If yis zero or negative, the string x is returned. For an example of the REPEAT 
built-in function, see “COPY” on page 392. 
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REVERSE 


RIGHT 


REVERSE 


REVERSE returns a nonvarying string that contains the elements of x in reverse 
order. 


The syntax for REVERSE is: 


pe—REVERSE ( x) AA > 


x expression. x must have a computational type and should have a string 
type. If x does not have a string type, it is converted to string (that is, from 
numeric to bit or character), according to the rules for concatenation. 


Example 


dcl source char value('HARPO' ); 
del target char(length(source)); 


target = reverse (source); /* "OPRAH" */ 


RIGHT returns a string that is the result of inserting string x at the right end of a 
string with length n and padded on the left with the character z as needed. If zis 
omitted, a blank is used as the padding character. 


The syntax for RIGHT is: 





pe——RIGHT (x, a aa 
AYA 


x expression. x must have a computational type and can have a character 
type. If not, it is converted to character. 


n expression that must have a computational type and is converted to 
FIXED BIN(M,0). 


z expression. If specified, z must result in a CHARACTER(1) NON- 
VARYING type. 


Example 


dcl source char value('One Hundred Dollars'); 
dcl target char(25); 


target = right (source, length(target), '*'); 
/* '*kkkkkOne Hundred Dollars’ tf 
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ROUND 


ROUND 


The value of x is rounded at a digit specified by n. The result has the mode, base, 
and scale of x. 


The syntax for ROUND is: 


>>—ROUND( x, 2.) -—--AALTv?rApAvNANNN > * 


x real expression. If xis negative, the absolute value is rounded and the 
sign is restored. 


n optionally-signed integer. It specifies the digit at which rounding is to 
occur. n must conform to the limits of scaling-factors for FIXED data. If n 
is greater than 0, rounding occurs at the (n)th digit to the right of the point. 
If n is zero or negative, rounding occurs at the (1-/n)th digit to the left of the 
point. 


The precision of a fixed-point result is given by: 
(max(1,min(p-qtitn,N)),n) 


where (p,q) is the precision of x, and N is the maximum number of digits allowed. 
Thus, n specifies the scaling factor of the result. 


In the following example: 


del X fixed dec(5,4) init(6.6666); 
put (round(X,2)); 


the value 6.67 is output. 


If xis FIXED, 
round(x,n) =sign(x)*(b ")* floor( abs(x)*(b” ©) +1/2) 


where b = 2 if x is BINARY; b = 10 if x is DECIMAL. 


If x is FLOAT and not equal to 0, 
round(.x,n) =sign(x)«(b°®” ”)* Floor( abs(x)*(b°* ) + 1/2) 


where b = radix(x) and e = exponent(x). 


If x is FLOAT and equal to 0, 
function round (x,n) = 0 
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SAMEKEY 


SCALE 


SEARCH 


SAMEKEY 


SAMEKEY returns a bit string of length 1 indicating whether a record that has been 
accessed is followed by another with the same key. 


The syntax for SAMEKEY is: 


>>—SAMEKEY ( X) A A A A A > 


x file reference. The file must have the RECORD attribute. 


Upon successful completion of an input/output operation on file x, or immediately 
before the RECORD condition is raised, the value accessed by SAMEKEY is set to 
'1'B if the record processed is followed by another record with the same key, and 
set to '0'B if it is not. 

The value accessed by SAMEKEY is also set to '0'B if: 


e An input/output operation that raises a condition other than RECORD also 
causes file positioning to be changed or lost 


e The file is not open 


e No current cursor position exists in the file. 


SCALE returns a floating-point value based on the formula x*(radix(x)"). The result 
has the base, mode, and precision of x. 


The syntax for SCALE is: 


p>—SCALE( x, 1.) ANN 


x expression declared REAL FLOAT. 


n expression that must have a computational type and is converted to 
FIXED BIN(M,0). 


SEARCH returns the first position in one string at which a character, bit, or graphic 
element of another string appears. It also allows you to specify the location at 
which to start searching. 


The syntax for SEARCH is: 





< 


p>e—SEARCH( oa er 


Chapter 17. Built-in functions, pseudovariables, and subroutines 433 


SEARCHR 


SEARCHR 


xX and y 
expressions. x specifies the string in which to search for any character, 
bit, or graphic in y. 


n expression. n specifies the location within x at which to begin searching. 
It must have a computational type and is converted to FIXED BIN(M,0). If 
nis less than 1 or if nis greater than 1 + length(x), the STRINGRANGE 
condition is raised, and the result is zero. 


Example 


dcl source char value(' PL/I is the Power '); 
dcl (first, last) char(25) varying; 

dcl wordlen fixed bin(31); 

dcl pos fixed bin(31); 

dcl start fixed bin(31); 

dcl end fixed bin(31); 


a) 


/* Find the first and the last word in "Source", assuming */ 
/* it contains at least one word =] 
start = verify(source, ' '); /* find start of lst word */ 
end = search(source, ' ',startt+l);/* find end of word af 


if end = 0 then 
end = length(source)+1; 
wordlen = end-start; 


first = substr(source,start,wordlen); /* 'PL/I' * f 
end = verifyr(source, ' '); /* find end of last word = */ 
start = searchr(source, ' ',end-1l); /* find start of word as 
wordlen = end-start; 

last = substr(source,start+l,wordlen); /* 'Power' * | 


The SEARCHR function performs the same operation as the SEARCH built-in func- 
tion except that 


° The search is done from right to left 
® The default value for n is LENGTH(x). 


The syntax for SEARCHR is: 





p>>—SEARCHR( Areal ; 4 


For argument descriptions and an example, refer to “SEARCH” on page 433. 
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SIGN 


SIGNED 


SIN 


SIGN 


SIGN returns a FIXED BIN(M,0) value that indicates whether x is positive, zero, or 
negative. 


The syntax for SIGN is: 


»>—S1GN( x) ANNAN 


x real expression. 


The returned value is given by: 


Value of x Value Returned 
x>0O +1 
x=0 0 
x <0 -1 


SIGNED returns a signed FIXED BIN value of x, with a precision specified by p and 
q. 


The syntax for SIGNED is: 


Ce 





x expression. 
p restricted expression that specifies the number of digits to be maintained 
throughout the operation. 
q _ restricted expression that specifies the scaling factor of the result. Fora 
fixed-point result, if p is given and q is omitted, a scaling factor of zero is 
the default. 


SIN returns a floating-point value that is an approximation of the sine of x. It has 
the base, mode, and precision of x. 


The syntax for SIN is: 


p>—S INC xX) > 


x expression whose value is in radians. 
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SIND 


SIND 


SINH 


SIZE 


SIND returns a real floating-point value that is an approximation of the sine of x. It 
has the base and precision of x. 


The syntax for SIND is: 


p> —S INDO X ) A 


x real expression whose value is in degrees. 
SINH returns a floating-point value that represents an approximation of the 
hyperbolic sine of x. It has the base, mode, and precision of x. 


The syntax for SINH is: 


pe —S INH X)- 


x expression whose value is in radians. 


SIZE returns a FIXED BIN(M,0) value giving the implementation-defined storage, in 
bytes, allocated to a variable x. 


The syntax for SIZE is: 


be—SIZE ( x)=" 


< 


a variable of any data type, data organization, alignment, and storage 
class, except as listed below. 


X cannot be: 


* A BASED, DEFINED, parameter, subscripted, or structure or union 
base-element variable that is an unaligned fixed-length bit string 


* A minor structure or union whose first or last base element is an una- 
ligned fixed-length bit string (except where it is also the first or last 
element of the containing major structure or union) 


* A major structure or union that has the BASED, DEFINED, or param- 
eter attribute, and which has an unaligned fixed-length bit string as its 
first or last element 


* A variable not in connected storage. 
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SQRT 


SQRT 


The value returned by SIZE(x) is the maximum number of bytes that could be 
transmitted in the following circumstances: 
declare F file record input 


environment(scalarvarying); 
read file(F) into(x); 


If x is: 


° A varying-length string, the returned value includes the length-prefix of the 
string and the number of bytes in the maximum length of the string 


° An area, the returned value includes the area control bytes and the maximum 
size of the area 


°* An aggregate containing areas or varying-length strings, the returned value 
includes the area control bytes, the maximum sizes of the areas, the length 
prefixes of the strings, and the number of bytes in the maximum lengths of the 
strings. 


Example 


dcl scids char(17) init('’See you at SCIDS!') static; 
dcl vscids char(20) varying init('See you at SCIDS!') static; 
dcl stg fixed bin(31); 


stg = storage (scids); /* 17 bytes */ 
stg = currentsize (scids); /* 17 bytes */ 
stg = size (vscids); /* 22 bytes */ 
stg = currentsize (vscids); {*- 19 bytes: 47 
stg = size (stg); /* 4 bytes */ 
stg = currentsize (stg): | /* 4 bytes */ 


For other built-in functions that set extents, refer to “CURRENTSIZE” on page 394 
and “MAXLENGTH?” on page 413. 


SQPT returns a floating-point value that is an approximation of the positive square 
root of x. It has the base, mode, and precision of x. 


The syntax for SQRT is: 


p>—SQRT ( x) ——-A SS NY})YyY}N Mm >» 


x expression. If x is real, it must not be less than zero. 
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STORAGE 


STORAGE 


Abbreviation: STG 


STORAGE is a synonym for SIZE. 


STRING 


STRING returns an element bit or character string that is the concatenation of all 
the elements of x. 


The syntax for STRING is: 


x 


>>—STRINGCX) A ANN > 


aggregate or element reference. 


STRING is restricted as follows: 


It cannot be applied to unions or structures containing unions 


If applied to a scalar, the scalar must be a nonvarying bit string, a nonvarying 
character string, a pictured character string, a pictured numeric string, or a non- 
varying graphic string. 


If applied to a structure, the structure must contain no padding bytes and the 
elements of the structure must be either: 


— All unaligned nonvarying bit strings 


— All character strings, each of which is either a nonvarying character string, 
a pictured string, or a pictured numeric string. 


— All nonvarying graphic strings 


If applied to an array, the array must be connected and all the elements in the 
array are subject to the restrictions for STRING. 


The following are valid STRING targets: 


dc 
1 


dc] 


dc] 


bit(8), 
bit(2), 
bit¢8): 


PO PO Ph &— 
OM Ww 


char(2), 
pic'aa', 
char(6); 


POP PM = 
NN =< >< 


> 


X char(2), 
Y pic'99', 
Z 


W 
2 
2 
2 Z char(6); 
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STRING pseudovariable 


The following are invalid STRING targets: 


dc] 
1A, 
2B bit(8) aligned, 
2G? “bateZ), 
20 bit(8) aligned; 


STRING pseudovariable 


The STRING pseudovariable assigns a string to x as if x were a string scalar. Any 
remaining strings in x are filled with blanks or zero bits, or, if varying-length, are 
given zero length. 


The syntax for STRING pseudovariable is: 


>>—STRING( x) ARAN NN > 
x aggregate or element reference. Each base element of x must be either 
all bit-string or all character-string. 
The STRING pseudovariable must not be used out of context. 


The pseudovariable is also subject to the restrictions of the STRING built-in func- 
tion. For more information on the restrictions, refer to 438. 


SUBSTR 
SUBSTR returns a substring, specified by y and z, of x. 


The syntax for SUBSTR is: 





< 


pre—SUBSTR( a a 
»Z 


x string expression. It specifies the string from which the substring is to be 
extracted. If x is not a string, it is converted to character. 

y expression that is converted to FIXED BIN(M,0). y specifies the length of 
the substring in x. 

z expression that is converted to FIXED BIN(M,0). z specifies the length of 


the substring in x. If zis zero, a null string is returned. If zis omitted, the 
substring returned is position y in x to the end of x. 


The STRINGRANGE condition is raised if z is negative or if the values of y and z 
are such that the substring does not lie entirely within the current length of x. It is 
not raised when y = LENGTH(x)+1 and z= 0. For an example of the SUBSTR 
built-in function, see “SEARCH” on page 433. 
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SUBSTR pseudovariable 


SUBSTR pseudovariable 


The pseudovariable assigns a string value to a substring, specified by y and z, of x. 
The remainder of xis unchanged. (Assignments to a varying string do not change 
the length of the string.) 


The syntax for SUBSTR pseudovariable is: 





< 


dee ae 
eZ 


x 


string-reference. x must not be a numeric character. 


expression. y specifies the starting position of the substring in x. It can 
be converted to a real fixed-point binary value. 


< 


expression. Z specifies the iengih of the subsiring in x. it can be con- 
verted to a real fixed-point binary value. If zis zero, a null string is 
returned. If zis omitted, the substring returned is position y in x to the end 


of x. 


Ni 


y and zcan be arrays only if xis an array. 


SUBTRACT 


SUBTRACT is equivalent to ADD(x,-y,p,q). 


The syntax for SUBTRACT is: 





< 


re a 
GF 


For details about arguments, refer to “ADD”.on page 382 for argument 
descriptions. 


SUCC 
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SUCC returns a floating-point value that is the smallest representable number 
larger than x. It is the base, mode, and precision of x. The OVERFLOW condition 
is raised if there is no such number. 


The syntax for SUCC is: 


p>—SUCC CX) __ i Or 


x expression declared REAL FLOAT. 
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SUM 


TAN 


TAND 


SUCC satisfies the following relationships: 
pred(succ(x)) = x 


{ 


“succ(pred(x)) = x 


-pred( -x) 
tiny (0d0) 


succ(x) 
succ(0d0 ) 


SUM returns the sum of all the elements in x. The base, mode, and scale of the 
result match those of x. 


The syntax for SUM is: 


pe —SUM CX) $A ee 


< 


array expression. If the elements of x are strings, they are converted to 
fixed-point integer values. 


If the elements of x are fixed-point, the precision of the result is (N,q), 
where N is the maximum number of digits allowed, and q is the scaling 
factor of x. 


If the elements of x are floating-point, the precision of the result matches 
x. 


TAN returns a floating-point value that is an approximation of the tangent of x. It 
has the base, mode, and precision of x. 


The syntax for TAN is: 


>>—TAN( x) A eee 


x expression whose value is in radians. 


TAND returns a real floating-point value that is an approximation of the tangent of 
x. It has the base and precision of x. 


The syntax for TAND is: 


»>>— | AND( xX) < 


xX real expression whose value is in degrees. 
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TANH 


TANH 


TANH returns a floating-point value that is an approximation of the hyperbolic 
tangent of x. It has the base, mode, and precision of x. 


The syntax for TANH is: 


pe —TANH( x) 


< 


expression whose value is in radians. 


TIME 
TIME returns a character string timestamp in the format HHMMSSTTT, in which: 


HH current hour 
MM current minute 
Ss current second 


The syntax for TIME is: 


Vv 
Vv 
L 
BH 
= 
im 
A 


The time zone and accuracy are system dependent. 


TINY 


TINY returns a floating-point value that is the smallest positive value x can assume. 
ii nas the base, mode, and precision, of x. 


The syntax for TINY is: 


»>—T INY( x) ANN ———_ > « 


+ 


expression declared REAL FLOAT. 


Tiny(x) is a constant and can be used in restricted expressions. 


TRANSLATE 


TRANSLATE returns a character string of the same length as x. 


The syntax for TRANSLATE is: 


>>—TRANSLATE( ) 


*< 





< 
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TRIM 


TRIM 


x character expression to be searched for possible translation of its charac- 
ters. 

y character expression containing the translation values of characters. 

z character expression containing the characters that are to be translated. If 


zis omitted, it defaults to collate(). 
TRANSLATE operates on each character of x as follows: 


If a character in x is found in z, the character in y that corresponds to that in z is 
copied to the result; otherwise, the character in x is copied directly to the result. If 
z contains duplicates, the leftmost occurrence is used. 


y is padded with blanks, or truncated, on the right to match the length of z. 


Any arithmetic or bit arguments are converted to character. TRANSLATE does not 
support GRAPHIC data. 


Example 


dcl source char value("If it's Tuesday, it must be Deutsche abend!") 
dcl target char(length(source)); 
del (to value ('ABCDEFGHIJKLMNOPOQRSTUVWXYZ'), 

from value ('abcdefghijkImnopgrstuvwxyz')) char(26); 


target = translate(source, to, from); 
/* "IF IT'S TUESDAY, IT MUST BE DEUTSCHE ABEND!" */ 


TRIM returns a nonvarying character string with characters trimmed from one or 
both ends. 


The syntax for TRIM is: 


ppe—TRIMCX, )-3 
eet 
»z 


xX, y, and z 
expressions. 





Each must have a computational type and should have the attribute 
CHARACTER. If not, they are converted. 


x is the string from which the characters defined by y are trimmed from the 
left, and the characters defined by z are trimmed from the right. 


lf zis omitted, it defaults to a CHARACTER(1) NONVARYING string con- 
taining one blank. 


If yand z are both omitted, they both default to a CHAR(1) NONVARYING 
string containing one blank. 
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TRUNC 


TRUNC 


UNSIGNED 


Example 


dcl source char value(" *** PL/I's got the Power! *** "); 
dcl target char(length(source)) varying; 


target = trim(source, ' ', '* '); 
/* "kkk PL/T's got the Power!" */ 


TRUNC returns an integer value that is the truncated value of x. If x is positive or 
O, this is the largest integer value less than or equal to x. If x is negative, this is 
the smallest integer value greater than or equal to x. This value is assigned to the 
result. 


The syntax for TRUNC is: 


pe—TRUNC( x) AN ee 


x real expression. 


The base, mode, scale, and precision of the result match those of x. Except when 
x is fixed-point with precision (p,q), the precision of the result is given by: 


(min(N,max(p-qtl,1)),0) 


where N is the maximum number of digits allowed. 


UNSIGNED returns an unsigned FIXED BINARY value of x, with a precision speci- 
fied by p and g. 


The syntax for UNSIGNED is: 


eT sp < 





x expression. 

p integer. It specifies the number of digits to be maintained throughout the 
operation. 

q optionally-signed integer. It specifies the scaling factor of the result. Fora 
fixed-point result, if p is given and q is omitted, a scaling factor of zero is 
the default. 
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UNSPEC 


UNSPEC 


UNSPEC returns a bit string that is the internal coded form of x. 


The syntax for UNSPEC is: 


pe —UNSPEC ( xX) A S$ A ee 


x scalar, array, structure, or union expression. 


The UNSPEC built-in function is subject to the following rules: 


° For aggregates, UNSPEC is allowed only for those that contain no padding 
bytes or bits. 


* The result will always be BIT(*) scalar. UNSPEC of an array does not yield an 
array of BIT("*). 


Note: Use of UNSPEC can affect the portability of your application program. 


The length of the returned bit string depends on the attributes of x, as shown in 
Figure 69. 


Figure 69 (Page 1 of 2). Length of bit string returned by UNSPEC 


Bit-String length Attribute of x 

8 SIGNED FIXED BIN (p,q), 1 <= p <= 7 
UNSIGNED FIXED BIN (p,q), 1 <= p <= 8 

16 SIGNED FIXED BINARY (p,q), 8 <= p <= 15 
UNSIGNED FIXED BINARY (p,q), 9 <= p <= 16 

32 ENTRY LIMITED 


SIGNED FIXED BINARY (p,q), 16 <= p <= 31 
UNSIGNED FIXED BINARY (p,q), 17 <= p <= 31 
FLOAT DECIMAL (p), 1 <= p <=6 

FLOAT BINARY (p), 1 <= p <= 21 

OFFSET2 

FILE constant or variable 

POINTER 


64 FLOAT BINARY(p), 21 < p < 53 
FLOAT DECIMAL(p), 7 <= p <= 16 
LABEL constant or variable 
ENTRY constant or variable 


128 FLOAT BINARY(p), 54 <= p <= 109 
FLOAT DECIMAL(p), 17 <= p <= 33 

n BIT (n) | 

8*n or 32767 CHARACTER (n) 


PICTURE (with character-string-value length of n) 
(when n>4096, a length of 32767 is returned) 


16*n GRAPHIC (n) 

16+n BIT VARYING where n is the maximum length of x 

16+(8*n) CHARACTER VARYING where n is the maximum length 
of x 
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UNSPEC pseudovariable 


Figure 69 (Page 2 of 2). Length of bit string returned by UNSPEC 


Bit-String length Attribute of x 

16+(16*n) GRAPHIC VARYING where n is the maximum length of x 
8*(n+16) AREA (n)2 

8*FLOOR(n) FIXED DECIMAL (p,q) where n = (p+2)/2 


Alignment and storage requirements for program control data can vary across sup- 
ported systems. 


If x is a varying-length string, its two-byte prefix is included in the returned bit string. 
If x is an area, the returned value includes the control information. 


UNSPEC pseudovariable 


The UNSPEC pseudovariable assigns a bit value directly to x; that is, without con- 
version. The bit value is padded, if necessary, on the right with '0'B to match the 
length of x, according to Figure 69. 


The syntax for the UNSPEC pseudovariable is: 


>> —UNSPEC CX) A A A A A > 


x reference. 


If x is a varying length string, its 2-byte prefix is included in the field to which the bit 
value is assigned. If x is an area, its control information is included in the receiving 
field. 


The pseudovariable is subject to the rules for the UNSPEC built-in function 
described in “UNSPEC” on page 445. 


Example 


dcl 1 strl nonasgn static, 
2 * fixed bin(15) init(16), /* '1000'X */ 
2 * char init('33'x), 
2 * bit. inate lb), 
2 bata) Bit tite lbs Ody. 1b, 70"), 
2 b3 bit(3) init('1ll'b), 
2 * char(0); 

dcl bit_strl bit(size(str1)*8); 

dcl bit_ba bit(dim(ba)*length(ba(1))); 

dcl bit_b3 bit(length(b3)); 


bit_ba = unspec(ba); /* result is scalar '1010'B not an array */ 
bit.b3° -= unspectbs)i - /* “111s zi. 
bit_strl = unspec(str1); /* '100033D7'B4 or 

'100033'B4 | '11010111'B i 
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VALID 


VERIFY 


VALID 


VALID returns a BIT(1) value that is '1'B under the following conditions: 


* \f xis PICTURE and its contents are valid for x's picture specification. 
* If xis FIXED DECIMAL and the data in x is valid fixed decimal data. 


If these conditions are not met, the result is '0'B. 


The syntax for VALID is: 


p>—VAL1D( x) ——-§_ A  — — —___—_—_—_—__——- 


x reference with either picture or fixed decimal type. 


VERIFY returns a real fixed-point binary value indicating the position in x of the 
leftmost character or bit that is not in y. It also allows you to specify the location 
within x at which to begin processing. 


If all the characters or bits in x do appear in y, a value of zero is returned. If x is 
the null string, a value of zero is returned. If x is not the null string and y is the null 
string, a value of one is returned. 


The syntax for VERIFY is: 





< 


Be NE ey 
i 


x string-expression. 
y string-expression. 
n expression. n specifies the location within x where processing begins. It 


must have a computational type and is converted to FIXED BIN(M,0). 


The STRINGRANGE condition, if enabled, is raised if 1 > n > length(x) + 1. Its 
implicit action and normal return give a result of O. Refer to “Results under 
DEFAULT(ANS)” on page 64 and “Results under DEFAULT(IBM)” on page 63 for 
the results of any necessary conversions. 


For an example of the VERIFY built-in function, see “SEARCH” on page 433. 
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VERIFYR 


VERIFYR 


The VERIFYR function performs the same operation as the VERIFY built-in function 
except that 


* The verification is done from right to left 
® The default value for n is LENGTH(x). 


The syntax for VERIFYR is: 





pear” 


For argument descriptions, refer to “VERIFY” on page 447. For an example, see 
“SEARCH” on page 433. 
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Chapter 18. Macro facility 


The PL/I Package/2 compiler provides a macro facility for source program alteration 
and conditional compilation. It is executed prior to compilation when you specify 
the MACRO compiler option. The macro facility scans the input source text and 
produces potentially modified output source text. The output can serve as input to 
the compiler or another source processor. 


The description of the macro facility assumes that you know the PL/I language 
described in this publication. Terms, syntax, and semantics are consistent with PL/I 
rules unless otherwise noted. 
Input source text is a stream of characters consisting of: 

* Macro facility statements. 


Macro facility statements are executed as they are encountered during the 
scan. Macro facility statements and clauses begin with a percent symbol (%). 


The macro facility executes these statements and alters the source text accord- 
ingly. Macro facility statements can cause alteration of the source text in any 
of the following ways: 


— Any identifier appearing in the source text can be changed to arbitrary text. 


— Portions of the source text can be conditionally selected as the output 
source text. 


— Source files can be included into the source text. 
* Control statements. These direct compilation process. 


® Source text. Text that is not one of the above. 


Macro facility output ' is a stream of characters consisting of: 
* Coniroi siaiemenis. Coniroi siatemenis that are processed and generatiy 
copied to the output source text. 
* Source text. Possibly altered source. 
You can specify compiler options for printing the input source text or writing the 
output source text to a file. Compiler options are described in PL/] Package/2 Pro- 
gramming Guide. 


Macro facility scan 


The macro facility starts its scan at the beginning of the source input and scans 
each character sequentially. Scanning proceeds as follows, for: 


Macro facility statements: These statements are executed when encountered. 
You can: 


* Declare identifiers using the %DECLARE statement and make them eligible for 
replacement. 


1 Macro facility replacement output is shown in a formatted style, while the actual output is unformatted. 
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* Change values of macro facility variables using the %assignment statement. 


°* Make an identifier eligible for replacement, by its value, in the source text using 
the %ACTIVATE statement. 


* Make an identifier ineligible for replacement, by its value, in the source text 
using the %DEACTIVATE statement. 


* Generate a message using the %NOTE statement. 
* Include a file using %INCLUDE. 


* Cause the macro facility to continue the scan at a different point in the source 
input using the %GO TO or %IF statement. 


Control statements: Control statements are generally copied into the macro 
facility output. A control statement must be on a line by itself. 


Replacing identifiers in source text: The source text, after replacement of any 
active identifiers by new values, is copied into the output text. The source text is 
scanned for: 


* Characters in the PL/I character set. Characters that are outside of the PL/I 
character set and are not part of constants and comments are treated as delim- 
iters and are copied unchanged to the output text. 


* PL/I constants or PL/| comments. These are copied unchanged to output text. 


* Active Identifiers. For an identifier to be replaced its value, the identifier must 
be active. A %DECLARE statement implicitly activates the identifier being 
declared. It can be deactivated by a %DEACTIVATE statement and reacti- 
vated by an %ACTIVATE statement. 


An identifier in the source text that matches the name of an active macro 
facility identifier is replaced in the output text by the value of that identifier. 


Identifiers can be activated with either the RESCAN or the NORESCAN 
options. If the NORESCAN option applies, the value is immediately placed into 
the output text. If the RESCAN option applies, the replaced value is rescanned 
to determine whether it contains any active identifiers that should be replaced. 
This rescanning and replacement activity continues until no further replace- 
ments can be made, at which time the replacement text is placed into the 
output text. Thus, insertion of a value into the output text takes place only after 
all possible replacements have been made. 


Replacement values must not contain % symbols, unmatched commenis, or 
unmatched single or double quotation marks that enclose constants. 


The scan terminates when all source input has been processed. The macro facility 
output is then complete for processing by the compiler or another processor. 


Character sets 


The macro facility supports only the single-byte character set, as defined in “Single- 
byte character set” on page 10. 
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Reserved keywords 


The macro facility reserves some keywords that have specific meaning to it. 
Reserved keywords cannot be used as identifier names. 


Macro facility keywords are shown in Figure 70. 


Figure 70. Macro facility keywords 


Keyword 


ACTIVATE 
ANSWER 
BY 
CHARACTER 
CODE 
COLUMN 
DEACTIVATE 
DECLARE 
DO 

ELSE 

END 
EXTERNAL 
FIXED 

GO TO 

IF 
INCLUDE 
INTERNAL 
ITERATE 
LEAVE 
LOOP 
KEYS 
MACRO 
MARGINS 
MESSAGE 
MSGLEVEL 


AIANDFanaA,l 
INVNECOVAIN 


NOSCAN 
NOTE 
OTHERWISE 
PAGE 
PROCEDURE 
RESCAN 
RETURN 
RETURNS 
REPEAT 
SELECT 
Reserved 
SKIP 
STATEMENT 
THEN 

TO 

TRACE 
UNTIL 
WHEN 
WHILE 


Abbreviation 


ACT 
ANS 


CHAR 
COL 


DEACT 
DCL 


EXT 


GOTO 


INT 


MAR 
MSG 


OTHER 


PROC 


STMT 


Status 
Reserved 


Unreserved 


Reserved 
Reserved 
Reserved 
Reserved 
Reserved 
Unreserved 
Unreserved 
Reserved (Note 1) 
Reserved 
Reserved 
Unreserved 


Unreserved 
Reserved 


Reserved 
Reserved 
Reserved 


Reserved 
Reserved 


Unreserved 


Reserved 


Unreserved 
Reserved 


Reserved 


Note 1: Neither GO nor TO when used by itself is reserved. 
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Data types and attributes 


The data types supported by the macro facility are: 


° Fixed point arithmetic data 
* Character string data 


For more information on data types refer to “Data types and attributes” on page 25. 


Fixed point data 


Character data 


Expressions 


Conversions 


Fixed point data has the FIXED attribute and the implied base and precision of 
BINARY(31,0). Attributes other than FIXED cannot be specified. It is used for 
arithmetic computation. 


Fixed point constants are written as FIXED DECIMAL constants, but without the 
decimal point. For more information on fixed point data, refer to “Coded arithmetic 
data and attributes” on page 30. 


Character data has the CHARACTER attribute and the implied VARYING attribute 
with length that has no logical upper limit. Attributes other than CHARACTER 
cannot be specified. It is used for text manipulation. 


Character constant and the X character constant are allowed. For more information 
on character data, refer to “Coded arithmetic data and attributes” on page 30. 


Expressions may use the concatenate operator and all arithmetic operators except 
exponentiation (**). 


Implicit conversions between FIXED and CHARACTER follow normal PL/I rules, 
except that FIXED always converts to exactly 8 characters. That is, for conversion 
purposes, FIXED data is treated as if it were declared as FIXED DECIMAL(5,0). 


Macro facility statements 


%ACTIVATE 


This section describes the macro facility statements in alphabetical order. 


The %ACTIVATE statement makes an identifier eligible for replacement by its value 
when the identifier is encountered in subsequent source text. 


The syntax for the %ACTIVATE statement is: 


>> —%—ACTIVATE—Y ident iffer —————— re 
RESCAN 
SCAN 
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Yassignment 


Abbreviation: %ACT 


identifier 
specifies the name of a macro facility identifier. 


RESCAN 
specifies that the identifier is replaced as many times as necessary. 


SCAN specifies that the identifier is replaced only once. ame keyword 
NORESCAN is a synonym for SCAN.) 


Issuing the %ACTIVATE statement for an identifier that is already active has no 
effect, except to change the scanning status. 


Yassignment 


A %assignment statement evaluates a macro facility expression and assigns the 
result to a macro facility variable. The variable need not be active nor have any 
specific scanning status. 


The syntax is: 


>>—%—reference— = —express1on—;——______6< 





reference 
specifies the name of a macro facility variable. 


%DEACTIVATE 


The %DEACTIVATE statement makes an identifier ineligible for replacement when 
the identifier is encountered in subsequent source text. 


DEACTIVATE statement is: 


PUNE Ue INee 


>>—%—DEACT | VATE identi Se ae a te eS < 


Abbreviation: %“DEACT 


identifier 
specifies the name of the macro facility identifier. 


The deactivation of an identifier causes it to be ineligible for replacement, but does 
not affect its value. Consequently, the reactivation of a deactivated identifier does 
not require the assignment of a replacement value. 


Deactivation of an inactive identifier has no effect. 
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%DECLARE 


%DO 


%DECLARE 


The %DECLARE statement establishes an identifier as a macro facility built-in func- 
tion or variable, and specifies the identifier's scanning status. 


Note: Before your application program refers to an identifier in macro facility state- 
ments, it must be declared, and the %DECLARE statement for the identifier must 
not be skipped as the result of a %GO TO statement, or an %IF-%THEN-% ELSE 
statement. 


The syntax for the %DECLARE statement is: 


se identifier 
; attributes 
ae iy rey ee ee, 


attributes: 





Abbreviations: %DCL for %DECLARE, CHAR for CHARACTER 


identifier 
specifies the name of a macro facility identifier or built-in function 


BUILTIN 
specifies that the identifier is a macro facility built-in function. For more 
information on macro facility built-in functions refer to 458. 


CHARACTER 
specifies character data. For more information on macro facility character 
data, refer to 453. 


FIXED specifies fixed point data. For more information on macro facility fixed 
point data, refer to “Fixed point data” on page 453. 


RESCAN 
specifies that the identifier is replaced as many times as necessary. 


SCAN specifies that the identifier is replaced only once. (The keyword 
NORESCAN is a synonym for SCAN.) 


NOSCAN 
specifies that the identifier is inactive and not replaced. 


The %DO statement, and its corresponding %END statement, delimit a macro 
facility do group. 


Macro facility statements and source text contained in the do group are processed 
only when the %DO statement is executed. 
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%END 


The syntax for the %DO statement is: 


The %END statement delimits a %DO statement. 


%END 


The syntax for the %END statement is: | 





eo ee 
label 


label must be the label of the most recent open %DO statement. 


%GO TO 


The %GO TO statement causes the scan to be resumed in the source text at the 
statement with the specified label. The target statement must appear after the 
%GO TO statement. 


The syntax for the %GO TO statement is: 


pr—%—G0 T0—/abe)—;- ———_—  - __——————______Y'“"« 


Abbreviation: %GOTO 


label _label on the target statement 


Macro facility statements between the %GO TO statement and the point where the 
scan is resumed are skipped and should be syntactically correct. 


%IF 


The %IF statement controls the flow of the macro facility scan. 


The syntax for the %IF statement is: 


p>>—*z—] F—relational -expression—ZTHEN—un a ees ee < 
4ELSE—uni t2 





relational-expression 
specifies the relational expression that is evaluated to true or false. If true, 
the %THEN clause is executed and the %ELSE clause, if present, is 
skipped. If false, the % THEN clause is skipped and the %ELSE clause, if 
present, is executed. 


456 PL/I Package/2 Language Reference 


%INCLUDE 


*%INCLUDE 


%THEN clause 
specifies unit1 as a %DO group or any macro facility statement, except 
%INCLUDE, %END, and %DECLARE. %INCLUDE and %DECLARE 
statements must be enclosed in a %DO group. 


%ELSE clause 
specifies unit2 as a %DO group or any macro facility statement other than 
%INCLUDE, %END, and %DECLARE. %INCLUDE and %DECLARE 
statements must be enclosed in a %DO group. 


Scanning resumes immediately following the %IF statement, unless, of course, a 
%GO TO statement in one of the clauses causes the scan to resume elsewhere. 
Macro facility statements between the %IF statement and the point where the scan 
is resumed are skipped, and should be syntactically correct. 


%IF statements can be nested in the same manner as described under “IF 
statement” on page 185 for nesting IF statements. 


For the syntax and a description, refer to “%INCLUDE statement” on page 187. 


The included file is treated normally, except that all macro facility statements, %DO 
groups, %GO TO targets, % THEN and %ELSE clauses must be fully contained 
with the same file. 


The scan then continues with the first character in the included file. The included 
file is scanned in the same manner as the input source text. Hence, included files 
contribute to the output source text being formed. 


%INCLUDE statements can be nested. In other words, included files can contain 
%INCLUDE statements. 


Example 
For example, assume that the external file named PAYRL contains the following: 


declare 1 Payroll, 
2 Name, 
3 Last character (30) varying, 
3 First character (15) varying, 
3 Middle character (3) varying, 
2 Curr; 
3 (Regular, Overtime) fixed decimal (8,2), 
2 * char(Q); 


Then the following macro facility statements generate two structure declarations in 
the output source text. The only difference between them is their names, Cum_Pay 
and Payroll. 

*declare Payroll character; 

*Payrol l='Cum_Pay'; 

include PAYRL; 

~deactivate Payroll; 

minclude PAYRL; 


Execution of the first %INCLUDE statement incorporates the file in PAYRL into the 


input source text. When the macro facility scan encounters the identifier Payrol] in 
this included file, it replaces it with the current value of the active macro facility 
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%NOTE 


%NOTE 


%null 


identifier Payroll, which is Cum_Pay. Further scanning of the included file results in 
no additional replacements. The macro facility scan then encounters the %DEAC- 
TIVATE statement and deactivates the macro facility identifier Payrol1. When the 
second %INCLUDE statement is executed, the file in Payrol] once again is incor- 
porated into the input source text. This time, however, scanning of the inciuded file 
results in no replacements. 


Refer to “%NOTE statement” on page 188. 


The %null statement causes no operation to be performed and does not modify the 
flow of macro facility scan. 


The syntax for the %null statement is: 


? 


SS 


Macro facility built-in functions 


These functions can be used in macro facility statements. The macro facility does 
not recognize these if they appear in the source text. 


When the name of a macro facility built-in function is encountered, it is processed 
as a built-in unless the name has already been declared with attributes other than 
BUILTIN. Once implicitly or explicitly declared as a built-in function, all subsequent 
appearances of the name will be treated as built-in function references. 


If the name is declared as something other than a built-in function, the name 
cannot be used as a built-in function. 


Function Description 

COLLATE Returns a character string consisting of all the 256 possible 
CHARACTER(1) values just once in an order known as the col- 
lating order. 

COMMENT Converts a character string into a valid PL/I comment. 

COMPILETIME Returns a character string containing the compilation date and time. 

COUNTER Returns a character string containing a numeric value that starts at 
‘00001 ' and is incremented by 1 each time that COUNTER is ref- 
erenced. 

INDEX Returns a value that indicates the Starting position of a character 
string within another character string. 

LENGTH Returns the current length of a string. 

MAX Returns the maximum arithmetic value from a set of two or more 


arithmetic expressions. 


MIN Returns the minimum arithmetic value from a set of two or more 
arithmetic expressions. 


QUOTE Converts a character string to a quoted character string. 
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COLLATE 


COMMENT 


COLLATE 


Function Description 

REPEAT Repeats a character string a specified number of times. 

SUBSTR Returns a substring from a string. 

SYSPARM Returns the character string value of the SYSPARM compiler 
option. 

SYSTEM Returns a character string representation of the SYSTEM option 
value in effect. 

SYSVERSION Returns a character string indicating the version and release of the 
compiler. 

TRANSLATE Returns a character string that is the translation of an input char- 


acter string. 


VERIFY Finds the position of the first character in the input string that is not 
present in the verification string. 


Refer to “COLLATE” on page 391. 


COMMENT returns a character string that represents x as a valid PL/I comment. 
If x contains /* or */ composite symbols, they are replaced by /> and </ respectively. 


The syntax is: 


>>—COMMENT ( x) A A AA A > 


x specifies the expression that is to be converted to a comment. 


Example 
In this example, the CHARACTER macro facility identifiers A and B are assigned 
character strings that are comments: 


Test: proc; 
dcl S_Varl character(35); 
del S_Var2 character(35); 
mdcl A character; 
“dc|l B character; 
*A = comment('What'); 
4B = comment('Name /* Ain''t it sweet? */"'); 


A; /* Generates the next line */ 
/*What*/ 
B /* Generates the next line gt | 
/*Name /> Ain't it sweet? </*/ 

end; 
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COMPILETIME 


COMPILETIME 


COMPILETIME returns a character string (of length 18) that contains the date and 
the time of compilation. 


The format of the timestamp is DDbMMMbYYbDHH.MI.SS, where: 


b is a blank character. 

DD is the current day. A leading zero in DD is replaced by a blank. 
MMM _ is the current month (abbreviated as JAN, FEB, and so on) 

YY is the current year. 

HH is the current hour. 

: is a separator. 

MI is the current minute. 

Ss is the current second. 


The syntax for COMPILETIME is: 


ee ea 
() 


Example 
For the following example, if the compilation date and time are September 2, 1991, 
2:15 am, the result is 2 SEP 91 02.15.00. 


Test: proc; 

*dc|l C char; 

%C = compiletime; pee’ 2 SEP OL 2 215200" Lt A 
end; 


COUNTER 


COUNTER returns a character string (of length 5) containing a numeric value with 
leading zeros. The first reference returns a value of '00001'. Each subsequent 
reference returns a number one greater than the previous reference. 


The syntax for COUNTER is: 


>>—COUNTE i < 
() 


Example 
Test: proc; 
mdcl (C,d) char; 
*C = counter; /* = '90001' ba 5 
4d = counter; /* = '90002' aa 
end; 
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INDEX 


LENGTH 


MAX 


MIN 


QUOTE 


REPEAT 


SUBSTR 


SYSPARM 


INDEX 


Refer to “INDEX” on page 407. 


Refer to “LENGTH” on page 409. 


Refer to “MAX” on page 412. 


Refer to “MIN” on page 413. 


QUOTE returns a character string that represents x as a valid quoted string. 


If x contains single quotation marks, each is replaced by two consecutive single 
quotation marks. 


The syntax is: 


r>—QUOTE( x) A + + 


x character expression that is to be converted to a quoted string. 


Example 


This: proc; 
dcl Book char; 
“dcl Title char; 


litle = "Shakespeare's ""Hamlet"""; /* Shakespeare's "Hamlet" */ 
Book = quote(Title); /* Generates ... i 
Book = 'Shakespeare''s "Hamlet"'; . 

end; 


Refer to “REPEAT” on page 430. 


Refer to “SUBSTR’” on page 439. 


SYSPARM returns the character string value of SYSPARM compiler option. See 
the description of the SYSPARM compiler option in the PL/) Package/2 Program- 
ming Guide for more information. 


SYSPARM allows information external to the program to be accessed without modi- 
fying the source program. 
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SYSTEM 


The syntax is: 


ae ie a oe < 
() 


Example 
pli mypgm (sysparm('TEST') macro 


Mypgm: proc; 
dcl Dept_num char(11); 
*dcl Group_id char; 
*dcl Group_num char; 


bif (sysparm = "DEVELOPMENT’)  %then /* false */ 
moroup_id = 'G32/001/DEV'; 
melse 
*d0; , 
if sysparm = 'SHIPPING' %then /* false */ 
*Group_id = 'G35/002/SHP' ; 
me 1S 
%d0; 
if (sysparm = 'TEST') %then /* true */ 
*Group_ID = 'G37/006/TST'; 
melSe 
*maroup_id = 'G99/000/MSC' ; 
mend ; 
mend ; 
Group_num = quote(Group_id_); 
Dept_num = Group_num:; /* Generates ... ced & 
Dept_num = 'G37/006/TST'; 
end; 


SYSTEM 


SYSTEM returns a character string that contains of the value of the SYSTEM com- 
piler option that is in effect. See the description of the SYSTEM compiler option in 
the PL/| Package/2 Programming Guide. 


The syntax is: 


Qj 


Example 
For the following example, assume that OS/2 is active. 


*process system(os2); 

This: proc; 
“dc! P_Varl char; 
dcl S_Varl character(20); 
4P_Varl = Quote(system); 


S Varl = P_Varl; /* Generates ... */ 
S VARI = ' O0S2 '; 
end; 
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SYSVERSION 


TRANSLATE 


VERIFY 


SYSVERSION 


SYSVERSION returns a character string (of length 31) indicating the name of the 
compiler and the version, release, and modification level. 


The format of the string is: 


nnnnnnnndvv remmbxxxxxXXXXXXXXXX 


in which: 
nnnnnnnn 

is the compiler name (PL/I) 
10 indicates a single blank 


vvrrmm 
is the compiler version (vv), release (rn, and modification level (mm) 


XX...XX Reserved for future use 


The syntax is: 


() 


Example 

This: proc: 
~dcl P_Varl char; 
dcl S$ Varl character(31); 
*P_Varl = Quote(sysversion); 


S Varl = P_Varl; /* Generates ... */ 
S Varl = 'PL/I VIRIMO XXXXXXXXXXXXXXX "3 
end; 


Refer to “TRANSLATE” on page 442. 


Refer to “VERIFY” on page 447. 
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Macro facility examples 


Macro facility examples 


Example 1 
Assume the input source text contains the following statements. 
declare A character, B fixed; 
A = 'BIC'; 
mB = 2; 
X= A; 
The macro facility produces the following output source text. 
X= » ere 
The macro facility statements declare A and 8 with the default status of RESCAN, 
assign the character string 'B+C' to A, and assign the constant 2 to B. 
The fourth line is source text. The current value of A, which is 'B+C', replaces A in 
the output source text. But this string contains the macro facility identifier B. Upon 
rescanning B, the macro facility finds that it is active. Hence, the value 2 replaces 
B in the output source text. Since identifier B has a data type of FIXED, it converted 
to an 8-character character string (‘bddbbpb2’). 
Further rescanning shows that 2 cannot be replaced. Scanning resumes with +C 
which, again, cannot be replaced. 
If, in the above example, the macro facility identifier A was activated by the fol- 
lowing statement: 
activate A norescan; 
The output source text would be: 
X = BH; 

Example 2 


The input source text contains the following statements. 


mdeclare I fixed, T character; 
“deactivate I; 


ml = 15; 
ml = 'ACI)'s 
S = I4T*3; 
bl = [+53 


mactivate I; 
Adeactivate T; 
R = I[*T*2; 


The output source text is as follows. (Replacement blanks for conversion from 
fixed to character are not shown.) 


S°= TeACI)*3} 
R = 20*1*2; 
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Limits 


Figure 71 summarizes the implementation limits for the PL/I Package/2 language 


elements. 


Figure 71 (Page 1 of 3). Language element limits 


Language 
Element 


Arrays 


Structures 


Arithmetic 
Precisions 


String and 
AREA Variables 


Built-In Func- 
tions 


Maximum number of arguments to the MAX and 
MIN functions 


Maximum values for the precision (p) in the ADD, 
BINARY, DECIMAL, DIVIDE, FIXED, FLOAT, 
MULTIPLY, PRECISION, and SUBTRACT func- 
tions 


Maximum values for the scale (q) in the ADD, 
BINARY, DECIMAL, DIVIDE, FIXED, MULTIPLY, 
PRECISION, and SUBTRACT functions 


Maximum number of digits (N) in the CEIL, 
FLOOR, MAX, MIN, MOD, ROUND and TRUNC 
functions 





Limit 


15 
-2147483647 
+2147483646 
15 

255 

31 

31 

18 

64 

127 

-128 

32767 

32767 

16383 
16777216 

64 


same as corre- 
sponding limit 
for arithmetic 
precision 


same as corre- 
sponding limit 
for arithmetic 
precisions 
same as corre- 
sponding limit 
for arithmetic 
precisions 
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Figure 71 (Page 2 of 3). Language element limits 


Language Description Limit 
Element 


Program Size Maximum length of an identifier 31 


Maximum number of procedures in a program 255 


Maximum number of lexical units (keywords, iden- 511 


tifiers, delimiters, etc) before a statement type can 
be resolved 


Maximum number of %PUSH statements 63 





Maximum number of DEFAULT-statements in a 31 
block 


Maximum number of LIKE-attributes in a block 63 


Maximum number of output expressions in a data- 60 
list 


Maximum number of repetitive DO-specifications in 15 
a data-list 


Maximum size of a data aggregate 2147483647 


Maximum number of arguments in a CALL or func- 255 
tion reference 


Maximum number of parameters for a procedure 255 
Maximum nesting of factored attributes 15 


Maximum nesting of BEGIN and PROCEDURE 30 
statements 


Maximum nesting of DO-groups 49 
Maximum nesting of IF statements 49 


Maximum nesting of SELECT-statements 49 
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Figure 71 (Page 3 of 3). Language element limits 


Language Description 

Element 

Miscellaneous Maximum number of picture characters in a char- 
acter picture 


Maximum number of bytes in a numeric picture 


Maximum number of numeric picture characters in 
a numeric picture 


Maximum number of bytes in the external repre- 
sentation of CHARACTER, X, BIT, BX, GRAPHIC, 
GX and M string constants 


The external representation includes all quotes 
and string suffixes. For example, the string 
'01010110'B has 11 bytes in its external specifica- 
tion, but only 1 byte in its internal representation. 
Similarly, the string ‘Ain't Misbehavin" has 21 
bytes in its external specification, but only 17 in its 
internal representation. 


Range of IEEE normalized floating-point numbers 


Range of hex floating-point numbers 








Limit 


511 


253 
15 


3072 


120 

60 
32,000 

1 

32,767 

{ 

126 

72 bytes 


+3.30E-4932 to 
+1.21E+4932, 0, 
-3.30E-4932 to 
-1.21E+4932 


+10E-78 to 
+10E75, 0, 
-10E-78 to 
+10E+75 
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Glossary 


A 


access. The act of referencing or retrieving data. 


action specification. In an ON statement, the on-unit 
or the single keyword SYSTEM, either of which speci- 
fies the action to be taken whenever an interrupt results 
from the raising of the named condition. The action 
specification can also include the keyword SNAP. 


activate (a block). To initiate the execution of a block. 
A procedure block is activated when it is invoked at an 
entry point. A begin block is activated when it is 
encountered in the normal flow of control, including a 
branch. 


active. The establishment of the validity for replace- 
ment of the value of a variable or the returned value of 
an entry name. The first activation must be the result of 
the appearance of the name in a %DECLARE state- 
ment. If an active variable or entry name is made inac- 
tive by the: %DEACTIVATE statement it may be 
activated again by an %ACTIVATE statement. 


active. (1) The state of a block after activation and 
before termination. (2) The state in which a pre- 
processor variable or preprocessor entry name is said 
to be when its value can replace the corresponding 
identifier in source program text. 


additive attribute. A file description attribute for which 
there are no defaults, and which, if required, must be 
stated explicitly or implied by another explicitly stated 
attribute. Contrast with alternative attribute. 


adjustable extent. Bound (of an array), length (of a 
string), or size (of an area) that might be different for 
different generations of the associated variable. Adjust- 
able extents are specified as expressions or asterisks 
(or by REFER options for based variables), which are 
evaluated separately for each generation. They cannot 
be used for static variables. 


aggregate. See dala aggregate. 


aggregate expression. An array, structure, or union 
expression. 


aggregate type. For any item of data, the specification 
whether it is structure, union, or array. 


allocated variable. A variable with which internal 
storage is associated and not freed. 


allocation. (1) The reservation of main storage for a 
variable. (2) A generation of an allocated variable. 
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alignment. The storing of data items in relation to 
certain machine-dependent boundaries (for example, a 
fullword or halfword boundary). 


alphabetic character. Any of the characters A through 
Z of the English alphabet and the alphabetic extenders 
#, $, and @ (which may have a different graphic repre- 
sentation in different countries). 


alphameric character. An alphabetic character or a 
digit. 


alternative attribute. A file description attribute that is 
chosen from a group of attributes. If none is specified, 
a default is assumed. Contrast with additive attribute. 


ambiguous reference. A reference that is not suffi- 
ciently qualified to identify one and only one name 
known at the point of reference. 


area. A declared portion of storage identified by an 
area variable with the AREA attribute. Its values may 
only be areas. 


area variable. A variable with the AREA attribute. Its 
values may only be areas. 


argument. An expression in an argument list as part 
of an invocation of a subroutine or function. 


argument list. A parenthesized list of one or more 
arguments, separated by commas, following an entry 
name constant, an entry name variable, a generic 
name, or a built-in function name. The list is passed to 
the parameters of the entry point. 


arithmetic comparison. A comparison of signed 
numeric values. See also bit comparison, character 
comparison. 


arithmetic constant. A fixed-point constant or a 
floating-point constant. Although most arithmetic con- 
stants can be signed, the sign is not part of the con- 
stant. 


arithmetic conversion. The transformation of a value 
from one arithmetic representation to another. 


arithmetic data. Data that has the characteristics of 
base, scale, mode, and precision. Coded arithmetic 
data and pictured numeric character data are included. 


arithmetic operators. Either of the prefix operators + 
and -, or any of the following infix operators: + — * / ** 
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arithmetic picture data. Decimal picture data con- 
taining the following types of picture specification 
characters: 


Decimal digit characters 

Zero suppression characters 

Sign and currency symbol characters 
Insertion characters 

Commercial characters 

Exponent characters. 


array. A named, ordered, collection of one or more 
data elements with identical attributes, grouped into one 
or more dimensions. 


array expression. An expression whose evaluation 
yields an array of values. 


array of structures. An ordered collection of identical 
structures specified by giving the dimension attribute to 
a structure name. 


array variable. A variable that represents an aggre- 
gate of data items that must have identical attributes. 
Contrast with structure variable. 


ASCII. (American National Standard Code for Informa- 
tion Interchange). The standard code, using a coded 
character set consisting of 7-bit coded characters (the 
8th bit for parity check) that is used for information inter- 
change among data processing systems, data commu- 
nication systems, and associated equipment. The ASCII 
set consists of control characters and graphic charac- 
ters. 


assignment. The process of giving a value to a vari- 
able. 


asynchronous operation. The overlap of an 
input/output operation with the execution of statements 
or the concurrent execution of procedures using multiple 
flows of control for different tasks. 


attachment of a task. The invocation of a procedure 
and the establishment of a separate flow of control to 
execute the invoked procedure (and procedures it 
invokes) asynchronously, with execution of the invoking 
procedure. 


attention. An occurrence, external to a task, that could 
cause an interrupt to the task. 


attribute. (1) A descriptive property associated with a 
name to describe a characteristic represented. (2) A 
descriptive property used to describe a characteristic of 
the result of evaluation of an expression. 


automatic storage allocation. The allocation of 
storage for automatic variables. 
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automatic variable. A variable whose storage is allo- 
cated automatically at the activation of a block and 
released automatically at the termination of that block. 


base. The number system in which an arithmetic value 
is represented. 


base element. The name of a structure member that 
is not a minor structure. 


base item. The automatic, controlled, or static variable 
or the parameter upon which a defined variable is 
defined. The name may be qualified and/or sub- 
scripted. 


based reference. A reference that has an explicit or 
implicit locater qualifier as its object. The name con- 
tained in a based reference necessarily refers to a 
based variable (that is, variable declared with the 
BASED attribute). 


based storage allocation. The allocation of storage 
for based variables. 


based variable. A variable that provides attributes for 
data (for example, data located in a buffer) for which 
the storage address is provided by a locater. Multiple 
generations of the same variable are accessible. It 
does not identify a fixed location in storage. 


begin-block. A collection of statements delimited by 
BEGIN and END statements. It is part of a program 
that delimits the scope of names. A begin-block is acti- 
vated either by error-handling ON-conditions or through 
ine normai fiow of controi inciuding any branch resuiting 
from a GOTO statement. 


binary. A number system whose only numerals are 0 
and 1. 


binary fixed-point value. An integer consisting of 
binary digits and having an optional binary point. Con- 
trast with decimal fixed-point value. 


binary floating-point value. An approximation of a 
real number in the form of a significand, which can be 
considered as a binary fraction, and an exponent, which 
can be considered as an integer exponent to the base 
of 2. Contrast with decimal floating-point value. 


bit. (1) A string composed of zero or more bits. 
(2) The smallest amount of space of computer storage. 


bit comparison. A left-to-right, bit-by-bit comparison of 
binary digits. See also arithmetic comparison, character 
comparison. 


bit constant. A series of binary digits enclosed in 
apostrophes and followed immediately by B or B1. 
Contrast with character constant. 


bit string constant. A series of hexadecimal digits 
enclosed in apostrophes and followed immediately by 
B4 or BX. 


bit value. A sequence of binary digits stored in con- 
secutive bits. 


bit string. A string composed of zero or more bits. 


bit string operators. The logical operators — (not), & 
(and), and | (or). 


block. A sequence of statements, processed as a unit, 
that specifies the scope of names and the allocation of 
storage for names declared within it. 


block heading statement. The PROCEDURE, BEGIN 
or PACKAGE statement that heads a block of state- 
ments. 


bound-pair list. A list specifying the lower and upper 
bounds of the valid indexes used to select elements of 
an array. 


bounds. The upper and lower limits of an array dimen- 
sion. 


break character. The underscore symbol (_ ). It can 
be used to improve the readability of identifiers. For 
instance, a variable could be called 
OLD_INVENTORY_TOTAL instead of 
OLDINVENTORYTOTAL. 


built-in function. A predefined function supplied by 
the language, such as a commonly used arithmetic 
function or a function needed by language facilities (for 
example, a function for manipulating strings or con- 
verting data). It is called by a built-in function refer- 
ence, such as SQRT (square root). 


built-in function reference. A built-in function name, 
having an optional and possibly empty argument list, 
that represents the value returned by the built-in func- 
tion. 


buffer. Intermediate storage, used in input/output oper- 
ations, into which a record is read during input and from 
which a record is written during output. 


bug. Generic term that encompasses anything that a 
program does that it was not designed to do. 


Cc 


call. (1) (verb) To invoke a subroutine use the CALL 
statement or CALL option (2) (noun) The using of the 
CALL statement or CALL option to invoke a subroutine. 


character comparison. A left-to-right, character-by- 
character comparison according to the collating 
sequence. See also arithmetic comparison, bit compar- 
ison. 


character constant. A sequence of characters 
enclosed in apostrophes; for example, ‘CONSTANT’. 


character set. A defined collection of characters. See 
language character set and data character set. 


character string. A string composed of zero or more 
characters enclosed in single quotes. 


character string picture data. Data described by a 
picture specification that must have at least one A or X 
picture specification character. 


closing (of a file). The dissociation of a file from a 
data set. 


coded arithmetic data. Data items that represent 
numeric values and are characterized by their base 
(decimal or binary), scale (fixed-point or floating-point), 
and precision (the number of digits each can have). 
This data is stored in a form that is acceptable, without 
conversion, for arithmetic calculations. 


code inspection. Debugging technique that involves 
selecting a written piece of source code and reading 
through it from the perspective of the computer. 


combined nesting depth. The sum of all 
PROCEDURE/BEGIN/ON, DO, SELECT, and 
IF... THEN...ELSE nestings in the program. 


comment. A string of zero or more characters used for 
documentation that are delimited by /* and */. 


commercial character. 


* CR (credit) picture specification character 
* DB (debit) picture specification character 
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comparison operator. An operator that can be used 
in an arithmetic, string, or logical relation to indicate the 
comparison to be done between the terms in the 
relation. The comparison operators are: 


= (equal to) 

> (greater than) 

< (less than) 

>= (greater than or equal to) 
<= (less than or equal to) 
—= (not equal to) 

—> (not greater than) 

—< (not less than). 


compile time. In general, the time during which a 
source program is translated into an object module. In 
PL/I, it is the time during which a source program can 
be altered (preprocessed), if desired, and then trans- 
lated into an object program. 


compiler options. Keywords that are specified to 
control certain aspects of a compilation, such as: the 
nature of the load module generated by the compiler, 
the types of printed output to be produced, the efficient 
use of the compiler, and the destination of error mes- 
sages. 


complex data. Arithmetic data, each item of which 
consists of a real part and an imaginary part. 


composite operator. An operator that consists of 
more than one special character, such as <=, **, and /*. 


compound statement. A statement that contains 
other statements. In PL/I, IF, SELECT, and ON are the 
only compound statements. See statement body. 


n that inina hain atrinan in 


i h 
concatenation Re ion tae Julio twy Si7iNGS wi 


LA dh da ee 1 ne ope 
the order specified, forming one string whose length is 
equal to the sum of the lengths of the two original 
strings. It is specified by the operator |I. 


condition. An exceptional situation, either an error 
(such as an overflow), or an expected situation (Such as 
the end of an input file). When a condition is raised 
(detected), the action established for it is processed. 
See also established action and implicit action. 


condition list. A list of one or more condition prefixes. 


condition name. Name of a PL/I-defined or 
programmer-defined condition 


condition prefix. A parenthesized list of one or more 
condition names prefixed to a statement. It specifies 
whether the named conditions are to be enabled. A 
condition list may be attached to any statement except 
DECLARE, DEFAULT, ENTRY, or % statements. 
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connected aggregate. An array or structure that has 
no inherited dimensions. 


connected reference. A reference to connected 
storage. It must be apparent, prior to execution of the 
program, that the storage is connected. 


connected storage. Main storage of an uninterrupted 
linear sequence of items that can be referred to by a 
single name. 


constant. (1) An arithmetic or string data item that 
does not have a name and whose value cannot change. 
(2) An unsubscripted label prefix of a file name or an 
entry name. 


constant reference. A value reference which has a 
constant as its object 


contained text. (1) All text in a procedure (including 
nested procedures) except its entry names and condi- 
tion prefixes of the PROCEDURE statement; (2) All text 
in a begin block except labels and condition prefixes of 
the BEGIN statement that heads the block. Internal 
blocks are contained in the external procedure. 


contextual declaration. The appearance of an identi- 
fier that has not been explicitly declared (in a DECLARE 
statement, as a label prefix, or in a parameter list), ina 
context that allows the association of specific attributes 
with the identifier. 


control character. A nonprinting character in a char- 
acter set whose occurrence in a particular context spec- 
ifies a control function. 


control code. A code point and its assigned control 
function meaning, for example, “end of transmission.” 
For 7-bit codes such as ASCIl, the first 32 code points 
are reserved for control purposes. For EBCDIC 8-bit 
codes, the first 64 code points are reserved. 


control format item. A specification used in edit- 
directed transmission to specify positioning of a data 
item within the stream or printed page. 


control variable. A variable that is used to control the 
iterative execution of a group, as in a DO statement. 


controlled parameter. A parameter for which the 
CONTROLLED attribute is specified in a declare state- 
ment. It can be associated only with arguments that 
have the CONTROLLED attribute. 


controlled storage allocation. The allocation of 
storage for controlled variables. 


controlled variable. A variable whose allocation and 
release are controlled by the ALLOCATE and FREE 
statements, with access to the current generation only. 


conversion. The transformation of a value from one 
representation to another to conform to a given set of 
attributes. 


cross section of an array. The elements represented 
by the extent of at least one dimension of an array. An 
asterisk in the place of a subscript in an array reference 
indicates the entire extent of that dimension. 


current generation. That generation (of an automatic 
or controlled variable) currently available by reference to 
the name of the variable. 


D 


data testing. Debugging technique that involves using 
test data to verify that a program operates as designed. 


DBCS. Double-byte character set. Each hexadecimal, 
2-byte DBCS code identifies a double-byte character. 
For example, Japanese extended Kanji characters are 
encoded in DBCS. 


data. Representation of information or of value in a 
form suitable for processing. 


data aggregate. A group of data items that can be 
referred to either individually or collectively. The types 
of aggregates are: arrays, unions and structures. 


data attribute. A keyword that specifies the type or 
kind of data to process. 


data character set. All of those characters whose rep- 
resentation is recognized by the computer in use. 


data-directed transmission. The type of stream- 
oriented transmission in which data is transmitted as a 
group, ended by a semicolon, where each item is of the 
form: 


name = constant 


data item. A single unit of data. It is synonymous with 
element. 


data list. In stream oriented data transmission, a 
parenthesized list of the data items used in GET EDIT 
and PUT EDIT statements. Contrast with format list. 


data set. A collection of data external to the program 
that can be accessed by reference to a single file name. 


data specification. The portion of a stream-oriented 
data transmission statement that specifies the mode of 
transmission (DATA, LIST, or EDIT) and includes the 
data list(s) and, for edit-directed mode, the format list(s). 


data stream. Data being transferred from or to a data 
set by stream-oriented transmission, as a continuous 
stream of data elements in character form. 


data transmission. The transfer of data from a data 
set to the program or vice versa. 


data type. A set of data attributes. 


deactivated. The state in which an identifier is said to 
be when its value cannot replace the corresponding 
identifier in Source program text. 


debugging. Process of removing bugs from a 
program. 


decimal. The number system whose numerals are 0 
through 9. 


decimal digit character. The picture specification 
character 9. 


decimal fixed-point constant. A constant consisting 
of one or more decimal digits with an optional decimal 
point. 


decimal fixed-point value. A rational number con- 
sisting of a sequence of decimal digits with an assumed 
position of the decimal point. Contrast with binary fixed- 
point value. 


decimal floating-point constant. A value made up of 
a Significand that consists of a decimal fixed-point con- 
stant, and an exponent that consists of the letter E fol- 
lowed by an optionally signed integer constant not 
exceeding three digits. 


decimal floating-point value. An approximation of a 
real number, in the form of a significand, which can be 
considered as a decimal fraction, and an exponent, 
which can be considered as an integer exponent to the 
base of 10. Contrast with binary floating-point value. 


decimal picture data. Arithmetic picture data specified 
by picture specification characters containing the fol- 
lowing types of picture specification characters: 


Decimal digit characters 

The virtual point picture character 
Zero-suppression characters 

Sign and currency symbol characters 
Insertion characters 

Commercial characters 

Exponent characters. 


declaration. (1) The establishment of an identifier as 
a name and the specification of a set of attributes 
(partial or complete) for it. (2) A source of attributes of 
a particular name. 


default. Describes a value, attribute, or option that is 
assumed when none has been specified. 
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defined item. A variable which is to be associated 
with some or all of the storage associated with the des- 
ignated base variable. 


delimit. To enclose one or more items or statements 
with preceding and following characters or keywords. 


delimiter. All comments and the following characters: 
percent, parentheses, comma, period, semicolon, colon, 
assignment symbol and blank. They define the limits of 
identifiers, constants, picture specifications, and 
keywords. 


descriptor. A skeletal form of a declaration in which 
declared names are omitted. See parameter descriptor. 


digit. One of the characters 0 through 9. 


dimension attribute. An attribute that specifies the 
number of dimensions of an array and indicates the 
bounds of each dimension. 


directive. A statement that directs the operation of the 
compiler. 


disabled. The state of a condition in which no interrupt 
occurs and no established action commences. 


do group. A sequence of statements delimited by a 
DO statement and ended by its corresponding END 
statement, used for control purposes. Contrast with 
block. 


do-loop. See iterative do-group. 


dummy argument. Temporary storage that is created 
automatically to hold the value of an argument that 
cannoi be passed by reference. 


dump. Printout of all or part of the storage used by a 
program as well as other program information, such as 
a trace of an error's origin. 


E 


EBCDIC. (Extended Binary-Coded Decimal Inter- 
change Code). A coded character set consisting of 
8-bit coded characters. 


edit-directed transmission. The type of stream- 
oriented transmission in which data appears as a con- 
tinuous stream of characters and for which a format list 
is required to specify the editing desired for the associ- 
ated data list. 


element. A single item of data as opposed to a col- 
lection of data items such as an array; a scalar item. 


element expression. An expression whose evaluation 
yields an element value. 
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element variable. A variable that represents an 
element; a scalar variable. 


elementary name. See base element. 


enabled. The state of a condition in which a particular 
on-unit results in a program interrupt that causes an 
established action to commence. 


entry constant. The label prefix of a PROCEDURE 
statement (an entry name). 


entry data item. A data item that represents an entry 
point to a procedure. 


entry expression. An expression whose evaluation 
yields an entry name. 


entry name. (1) An identifier that is explicitly or con- 
textually declared to have the ENTRY attribute (unless 
the VARIABLE attribute is given) or (2) Has the value 
of an entry variable with the ENTRY attribute implied. 


entry point. A point in a procedure at which it may be 
invoked. 


entry reference. An entry constant, an entry variable 
reference, or a function reference that returns an entry 
value. 


entry variable. A variable to which an entry value can 
be assigned. It must have both the ENTRY and VARI- 
ABLE attributes. 


entry value. The entry point represented by an entry 
constant; the value includes the environment of the acti- 
vation that is associated with the entry constant. 


environment (of an activation). Information associ- 
ated with and used in the invoked block regarding data 
declared outside the block. 


environment (of a label constant). Identity of the par- 
ticular activation of a block to which a reference to a 
statement-label constant applies. This information is 
determined at the time a statement-label constant is 
passed as an argument or is assigned to a statement- 
label variable, and it is passed or assigned along with 
the constant. 


established action. The action taken when a condi- 
tion is raised. See also implicit action and 
ON-statement action. 


epilogue. Those processes that occur automatically at 
the termination of a block or task. 


evaluation. The reduction of an expression to a single 
value, an array of values, or a structured set of values. 


explicit declaration. The appearance of an identifier 
(a name) in a DECLARE statement, as a label prefix, or 
in a parameter list. Contrast with implicit declaration. 


exponent characters. The following picture specifica- 
tion characters: 


1. K and E, which are used in floating-point picture 
specifications to indicate the beginning of the expo- 
nent field. 


2. F, the scaling factor character, specified with an 
integer constant that indicates the number of 
decimal positions the decimal point is to be moved 
from its assumed position to the right (if the con- 
Siant is positive) of to the left (if the constant is neg- 
ative). 


expression. (1) A notation, within a program, that 
represents a value, an array of values, or a structured 
set of values; (2) A constant or a reference appearing 
alone, or a combination of constants and/or references 
with operators. 


extended alphabet. Upper and lower case alphabetic 
characters A through Z, $, @ and #. 


extent. (1) The range indicated by the bounds of an 
array dimension, by the length of a string, or by the size 
of an area (2) The significant allocations in an area. 


external name. A name (with the EXTERNAL attri- 
bute) whose scope is not necessarily confined only to 
one block and its contained blocks. 


external procedure. A procedure that is not contained 
in any other procedure. 


extralingual character. Characters (such as $, @, 
and #) that are not classified as alphanumeric or 
special. This group can include characters that are 
determined with the NAME compiler option. 


F 


factoring. The application of one or more attributes to 
a parenthesized list of names in a DECLARE statement, 
eliminating the repetition of identical attributes for mul- 
tiple names 


field (in the data stream). That portion of the data 
stream whose width, in number of characters, is defined 
by a single data or spacing format item. 


field (of a picture specification). Any character-string 
picture specification or that portion (or all) of a numeric 
character picture specification that describes a fixed- 
point number. 


file. A named representation, within a program, of a 
data set or data sets. A file is associated with the data 
set(s) for each opening. 


file constant. A name declared for a file and for which 
a complete set of file description attributes exists during 
the time that the file is open, and with which each file 
must be associated. 


file description attributes. Keywords that describe 
the individual characteristics of each file constant. See 
also alternative attribute and additive attribute. 


file expression. An expression whose evaluation 
yields a file name. 


file name. A name declared for a file. 


file variable. A variable to which file constants can be 
assigned. It has the attributes FILE and VARIABLE and 
cannot have any of the file description attributes. 


fixed-point constant. See arithmetic constant. 
floating-point constant. See arithmetic constant. 
flow of control. Sequence of execution. 


footprints. Output markers in a program that indicate 
where a program is in its execution flow or display the 
values of identifiers. Used as a debugging technique. 


format item. A specification used in edit-directed data 
transmission to describe the representation of a data 
item in the stream (data format item) or the specific 
positioning of a data item within the stream (control 
format item). 


format list. In stream oriented data transmission, a list 
specifying the format of the data item on the external 
medium. Contrast with data list. 


fully-qualified name. A qualified name that includes 
all the names in the hierarchical sequence above the 
structure member to which the name refers, as well as 
the name of the member itself. 


function (programmer-specified or built-in). A pro- 
cedure that has a RETURNS option in the PROCE- 
DURE statement. It is invoked by the appearance of 
one of its entry names in a function reference and it 
returns a scalar value to the point of reference. Con- 
trast with subroutine. 


function reference. An entry constant or an entry vari- 
able, either of which must represent a function, followed 
by a possibly empty argument list. Contrast with sub- 
routine call. 
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G 


generation (of a variable). The allocation of a static 
variable, a particular allocation of a controlled or auto- 
matic variable, or the storage indicated by a particular 
locator qualification of a based variable or by a defined 
variable or parameter. 


generic descriptor. A descriptor used in a GENERIC 
attribute. 


generic key. A character string that identifies a class 
of keys. All keys that begin with the string are 
members of that class. For example, the recorded keys 
“ABCD,” “ABCE,” and “ABDF,” are all members of the 
classes identified by the generic keys “A” and “AB,” and 
the first two are also members of the class “ABC”; and 
the three recorded keys can be considered to be unique 
members of the classes “ABCD,” “ABCE,” “ABDF,” 
respectively. 


generic name. The name of a family of entry names. 
A reference to the generic name is replaced by the 
entry name whose parameter descriptors match the 
attributes of the arguments in the argument list at the 
point of invocation. 


group. A collection of statements contained within 
larger program units. A group is either a do-group ora 
select-group and it can be used wherever a single 
statement can appear, except as an on-unit. 


H 


hexadecimal. Portaining to a numbering system with a 


hAanan af aivutaan: HA wmiuimbhava rian than Aiaitan AN thw, 
WaoGd VI VIALOCUCI, Vaid numySrs usor ult GiGitS Vv invougn 


9 and the characters A through F, where A represents 
10 and F represents 15. 


identifier. A string of characters, not contained in a 
comment or constant, and preceded and followed by a 
delimiter. The first character of the identifier must be 
one of the 29 extended alphabetic characters. The 
others, if any, can be extended alphabetic, digit, or the 
break character. 


IEEE. Institute of Electrical and Electronics Engineers. 


implicit. The action taken in the absence of an explicit 
statement. 


implicit action. The action established for a condition 
when the program is activated and that remains estab- 
lished unless overridden by disabling the condition or by 
the processing of an ON statement for the same condi- 
tion. Contrast with ON-statement action. 
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implicit declaration. The appearance of a name ina 
program when it has not been explicitly declared. A 
default set of attributes is assumed for the name. 


implicit opening. The opening of a file as the result of 
an input or output statement other than the OPEN state- 
ment. 


infix operator. An operator that appears between two 
operands. 


inherited dimensions. For a structure field, those 
dimensions that are derived from the containing struc- 
tures. If the structure field is a scalar variable, the 
dimensions consist entirely of its innerited dimensions. 
If the structure field is an array, its dimensions consist 
of its inherited dimensions plus its explicitly declared 
dimensions. A structure field with one or more inherited 
dimensions is referred to as an unconnected aggregate. 
Contrast with connected aggregate. 


initial procedure. See main procedure. 


input/output. The transfer of data between auxiliary 
medium and main storage. 


insertion point character. A picture specification 
character that is, on assignment of the associated data 
to a character string, inserted in the indicated position. 
When used in a P-format item for input, an insertion 
character serves as a checking picture character. 


instruction pointer. A pointer that provides address- 
ability for a machine instruction in a program. 


integer. A sequence of digits. 


integral boundary. The multiple of any 8-bit unit of 
information on which data can be aligned. 


interleaved array. An array whose name refers to 
non-connected storage. 


interleaved subscripts. A subscript notation used with 
subscripted qualified names in which not all of the nec- 
essary subscripts immediately follow the same compo- 
nent name. 


internal block. A block that is contained in another 
block. 


internal name. A name that is not known outside the 
block in which it is declared. 


internal procedure. A procedure that is contained in 
another block. Contrast with external procedure. 


internal text. Text that is contained in a block, but not 
contained in any other block nested within it. 


interrupt. The redirection of the program's flow of 
control (possibly temporary) as the result of raising a 
condition or attention. 


invocation. The activation of a procedure. 
invoke. To activate a procedure. 


invoked procedure. A procedure that has been acti- 
vated. 


invoking block. A block containing a statement that 
activates a procedure. 


iteration factor. (1) In an INITIAL attribute specifica- 
tion, an expression that specifies the number of consec- 
utive elements of an array that are to be initialized with 
a given constant. (2) In a format list, an expression 
that specifies the number of times a given format item 
or list of items is to be used in succession. 


iterative do-group. A do-group whose DO statement 
specifies a control variable and/or a WHILE or UNTIL 
option. 


K 


key. Data that identifies a record within a direct-access 
data set. See source key and recorded key. 


keyword. An identifier that has a specific meaning to 
the compiler when used in a defined context. 


keyword statement. A simple statement that begins 
with a keyword, indicating the function of the statement. 


known. (applied to a name) Recognized with its 
declared meaning. A name is known throughout its 
scope. 


L 


label. A name used to identify a statement other than . 
a PROCEDURE or an ENTRY statement. A statement 
label. 


label data item. A label constant or the value of a 
label variable. 


label constant. A name written as the label prefix of a 
statement (other than PROCEDURE or ENTRY) so that, 
during execution, program control can be transferred to 

that statement through a reference to its label prefix. 


label list (of a statement). All of the label prefixes of 
a statement. 


label list (of a label variable declaration). A paren- 
thesized list of one or more statement-label constants 
immediately following the keyword LABEL to specify the 


range of values that the declared variable may have. 
Names in the list are separated by commas. When 
specified for a label array, it indicates that each element 
of the array may assume any of the values listed but no 
other. 


label prefix. A label prefixed to a statement. 


label variable. A variable declared with the LABEL 
attribute so that it can assume as its value a label con- 
stant at some other point in the program. 


language character set. A set of characters that has 
been defined to represent program elements in the 
source lanquaae. 


leading zeroes. Zeros that have no significance in the 
value of an arithmetic integer. All zeros to the left of 
the first significant integer digit of a number. 


level-number. A number that precedes a name ina 
DECLARE statement and specifies the organization of 
the structure in that statement. 


level-one variable. A major structure name. Any 
unsubscripted variable not contained within a structure. 


lexically. Relating to the left-to-right order of units. 


list-directed. The type of stream-oriented transmission 
in which data in the stream appears as constants sepa- 
rated by blanks or commas and for which formatting is 
provided automatically. 


locator. A type of variable that identifies a location in 
storage. 


locator qualification. In a reference to a based vari- 
able, either a locator variable or function reference con- 
nected by an arrow to the left of a based variable to 
specify the generation of the based variable to which 
the reference refers, or the implicit connection of a 
locator variable with the based reference. 


locator value. A value that identifies the storage 
address. 


locator variable. A variable whose value identifies the 
location in main storage of a variable or a buffer. It has 
the POINTER or OFFSET attribute. 


locked record. A record in an EXCLUSIVE DIRECT 
UPDATE file that is available to only one task at a time. 


logical level (of a structure member). The depth 
indicated by a level number when all level numbers are 
in direct sequence (when the increment between suc- 
cessive level numbers is one). 


logical operators. The bit-string operators — (not), & 
(and), and | (or). 
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loop. A sequence of instructions that is executed iter- 
atively. 


lower bound. The lower limit of an array dimension. 


main procedure. An external procedure whose PRO- 

CEDURE statement has the OPTIONS (MAIN) attribute. 
This procedure is invoked automatically as the first step 
in the execution of a program. 


major structure. A structure whose name is declared 
with level number 1. 


manifest declaration. The declaration of a name ina 
DECLARE statement. 


member. A subdivision of a structure consisting either 
of a minor structure or of a scalar. 


minor structure. A structure that is contained within 
another structure. The name of a minor structure is 
declared with a level number greater than one. 


mode (of arithmetic data). An attribute of arithmetic 
data—it is either real or complex. 


multiple declaration. (1) Two or more declarations of 
the same identifier internal to the same block without 
different qualifications. (2) Two or more external decla- 
rations of the same identifier with different attributes in 
the same program. 


multiprocessing. The use of a computing system with 
two or more processing units to execute two or more 
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multiprogramming. The use of a computing system to 
execute more than one program concurrently, using a 
single processing unit. 


multitasking. A facility that allows a programmer to 
execute more than one PL/I procedure simultaneously. 


N 


name. Any identifier that the user assigns to a variable 
or to a constant. An identifier appearing in a context 
where it is not a keyword. Sometimes called a user- 
defined name. 
nesting. The occurrence of: 

* A block within another block 

* A group within another group 


* An IF statement in a THEN clause or in an ELSE 
clause 
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* A function reference as an argument of a function 
reference 


* A remote format item in the format list of a 
FORMAT statement 


* A parameter descriptor list in another parameter 
descriptor list 


* An attribute specification within a parenthesized 
name list for which one or more attributes are being 
factored. 


non-connected storage. Separate locations in 
storage containing related items of data that can be 
referred to by a single name but that are separated by 
other data items not referred to by that name. 


normal default. The default for an attribute (or set of 
attributes) that occurs in the absence of one or more 
DEFAULT statements in a program. 


nonprintable types. A type describing data that 
cannot be transmitted using the PUT LIST statement. 
Nonprintabie types are all scalar types including the 
graphic type, other than the printable scalar types. 


null locator value. A special locator value that cannot 
identify any location in internal storage. It gives a posi- 
tive indication that a locator variable does not currently 
identify any generation of data. 


null statement. A statement that contains only the 
semicolon symbol (;). It indicates that no action is to be 
taken. 


null string. A character or bit string with a length of 
zero. 


numeric-character data. See decimal picture data. 


O 


object. A collection of data referred to by a single 
name. 


offset variable. A locator variable with the OFFSET 
attribute, whose value identifies a location in storage 
relative to the beginning of an area. 


ON-condition. An occurrence, within a PL/I program, 
that could cause a program interrupt. It may be the 
detection of an unexpected error or of an occurrence 
that is expected, but at an unpredictable time. 


ON-statement action. The action explicitly established 
for a condition when the condition is raised. The 
ON-statement action overrides or suspends any previ- 
ously established action unless it is overridden by a 
further ON-statement for the same condition or the 


block it was processed in ends. Contrast with implicit 
action. 


on-unit. The specified action to be executed on 
detection of the enabled condition named in the con- 
taining ON statement. This excludes SYSTEM and 
SNAP. 


opening (of a file). The association of a file with a 
data set and the completion of a full set of attributes for 
the file name. 


operand. An expression to whose value an operator is 
applied. 


operational expression. An expression that consists 
of one or more operators. 


operator. A symbol specifying an operation to be per- 
formed. 


option. A specification in a statement that may be 
used to influence the execution or interpretation of the 
statement. 


p 


packed decimal. The internal representation of a 
fixed-point decimal data item. 


padding. (1) One or more characters or bits concat- 
enated to the right of a string to extend the string to a 
required length. For character strings, padding is with 
blanks. For bit strings, padding is with zeros. (2) One 
or more characters or bits inserted in a structure so that 
the structure elements have the required alignment. 


parameter. A name in a procedure that is represents 
an argument passed to that procedure. 


parameter descriptor. The set of attributes specified 
for a single parameter in an ENTRY attribute specifica- 
tion. 


parameter descriptor list. The list of all parameter 
descriptors in an ENTRY attribute specification. 


parameter list. A parenthesized list of one or more 
parameters, separated by commas and following either 
the keyword PROCEDURE in a procedure statement or 
the keyword ENTRY in an ENTRY statement. The list 
corresponds to a list of arguments passed at invocation. 


partially-qualified name. A qualified name that is 
incomplete. It includes one or more, but not all, of the 
names in the hierarchical sequence above the structure 
member to which the name refers, as well as the name 
of the member itself. 


path testing. Debugging technique that involves 
selecting test data that will enable the testing of all parts 
of a program. 


picture data. Arithmetic data represented in character 
form. 


picture specification. A data item that has a numeric 
value but that can also be represented as a character 
value according to the editing characters specified in 
the item’s declaration. 


picture specification character. Any of the charac- 
ters that can be used in a picture specification. 


point of invocation. The point in the invoking block at 
which the procedure reference to the invoked procedure 
appears. 


pointer. A type of variable that identifies a location in 
storage. 


pointer value. A value that identifies the storage 
address. 


pointer variable. A locator variable with the POINTER 
attribute, whose value identifies an absolute location in 
main storage. 


precision. The number of digits contained in a fixed- 
point data item, or the minimum number of significant 
digits (excluding the exponent) maintained for a floating- 
point data item. 


prefix. A label or a parenthesized list of one or more 
condition names included at the beginning of a state- 
ment. 


prefix operator. An operator that precedes an 
operand and applies only to that operand. The prefix 
operators are + (plus), — (minus), and — (not). 


preprocessor. A program that examines the source 
program for preprocessor statements which are then 
executed, resulting in the alteration of the source 
program. 


preprocessor statement. A special statement 
appearing in the source program that specifies how the 
source program text is to be altered. It is executed as it 
is encountered by the preprocessor. 


problem data. Coded arithmetic, bit, character, and 
picture data that represents values processed by the 
program. 


procedure. A collection of statements, delimited by 
PROCEDURE and END statements. A procedure is a 
program or a part of a program, delimits the scope of 
names, and is activated by a reference to its entry 
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name. See also external procedure and internal proce- 
dure. 


procedure reference. An entry constant or variable or 
a built-in function name. The variable may be followed 
by one or more argument lists. It may appear in a 
CALL statement or CALL option, or as a function refer- 
ence. 


processor. A program that prepares source program 
text for execution. 


program. A set of one or more external procedures, 
one of which must have the OPTIONS(MAIN) specifica- 
tion in its procedure statement. 


program control data. Area, locator, label, format, 
entry, and file data that is used to control the proc- 
essing of a PL/I program. 


printable type. A type describing data that can be 
transmitted using the PUT LIST statement. Printable 
types are the numeric types, the bit and character 
types, and the pictured types. 


prologue. The processes that occur automatically on 
block activation. 


pseudovariable. Any of the built-in function names 
that can be used to specify a target variable. 


pseudovariable reference. A value reference which 
has a pseudovariable as its object. 


Q 


qualified name. A hi 


structure members, connected by periods, used to iden- 
tify a component of a structure. Any of the names may 
be subscripted. : 


R 


range (of a default specification). A set of identifiers 
and/or parameter descriptors to which the attributes in a 
default specification of a DEFAULT statement apply. 


record. The logical unit of transmission in a record- 
oriented input or output operation. 


recorded key. An identifier within a set of data ele- 
ments recorded in a direct-access volume to identify an 
associated data record. 


record-oriented data transmission. The transmission 
of data in the form of separate records. Contrast with 
stream data transmission. 
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recursive procedure. An active procedure that can be 
called from within itself or from within another active 
procedure. 


reentrant procedure. A procedure that can be reacti- 
vated while it is still active in another active procedure. 


REFER expression. The expression preceding the 
keyword REFER, from which an original bound, length, 
or size is taken when a based variable containing a 
REFER option is allocated, either by an ALLOCATE or 
LOCATE statement. 


REFER object. The variable in a REFER option that 
specifies the current bound, length, or size for a 
member of a based structure. The REFER object must 
be a member of the structure. It must not be locator- 
qualified or subscripted, and it must precede the 
member declared with the REFER option. 


reference. The appearance of a name, except in a 
context that causes explicit declaration. 


remote format item. The letter R specified in a format 
list together with the label of a separate format state- 
ment. The format statement is used by edit-directed 
data transmission statements to control the format of 
data being transmitted. 


repetition factor. A parenthesized unsigned decimal 
integer constant that specifies: 


1. The number of occurrences of a string configuration 
that make up a string constant. 


2. The number of occurrences of a picture specifica- 
tion character in a picture specification. 


repetitive specification. An element of a data list that 
specifies controlled iteration to transmit one or more 
data items, generally used in conjunction with arrays. 


restricted expression. An expression whose value is 
calculated at compile-time and used as a constant. 


returned value. The value returned by a function pro- 
cedure to the point of invocation. 


returns descriptor. A descriptor used ina RETURNS 
attribute, and in the RETURNS option of the PROCE- 
DURE and ENTRY statements. 


run unit. A set of PL/I programs, each of which is 
called by some other PL/I program within the set, 
except for the initially called program, which is called 
from outside the set. A PL/I run unit is suspended 
when a program in the run unit calls a non-PL/| 
program, and is resumed when the called program 
returns control to the PL/I program that called it. A PL/I 
run unit ends when the initially called PL/I program 
returns control to the non-PL/I program that originally 
called the initial program and so started the run unit. 


S 


scalar. A type of program object that contains either 
string or numeric data. It provides the byte string it is 
mapped to with representation and operational charac- 
teristics. Contrast with pointer. 


scalar item. A single item of data; an element. 
scalar type. The type describing scalar data. 


scalar variable. A variable that represents a single 
data item. 


scale. A system of mathematical notation whose rep- 
resentation of an arithmetic value is either fixed-point or 
floating-point. 


scale factor. A specification of the number of frac- 
tional digits in a fixed-point number. 


scope (of a condition prefix). The portion of a 
program throughout which a particular condition prefix 
applies. 


scope (of a declaration). The portion of a program 
throughout which the meaning of a particular name 
does not change. 


scope (of a name). The portion of a program 
throughout which the meaning of a particular name 
does not change. 


select-group. A sequence of selection clauses delim- 
ited by SELECT and END statements. The select- 
group is used for control purposes. 


selection clause. A WHEN or OTHERWISE clause of 
a select-group. 


self-defining data. A data item, or an aggregate of 
data items, that includes descriptive information about 
the attributes of the data, such as values for adjustable 
bounds or lengths. 


separator. See delimiter. 


sign and currency symbol characters. The picture 
specification characters. S, +, —, and $ (or other national 
currency symbols). They can be used: 


* As static characters in which case they are speci- 
fied only once in a picture specification and appear 
in the associated data item in the position in which 
they have been specified. 


* As drifting characters, in which case they are speci- 
fied more than once (as a string in a picture specifi- 
cation) but appear in the associated data item at 
most once, immediately to the left of the significant 
portion of the data item. 


significant allocation. Any unfreed allocation in an 
area and any freed allocation that lies between the start 
of the area and the end of the unfreed allocation that is 
farthest from the start of the area. If a subsequent allo- 
cation of the same size is made in the same allocation, 
the original allocation ceases to be significant. 


simple statement. See statement body. 


source key. A key referred to in a record-oriented 
transmission statement that identifies a particular record 
within a direct-access data set. 


source program. A program that serves as input to 
the compiler. The source program may contain pre- 
processor statements. 


source variable. A variable whose value is to be 
assigned or to take part in some other operation. 


standard default. The alternative attribute or option 
assumed when none has been specified and there is no 
applicable DEFAULT statement. 


standard file. A file assumed by the processor in the 
absence of a FILE or STRING option in a GET or PUT 
statement. SYSIN is the standard input file and 
SYSPRINT is the standard output file. 


standard system action. Action specified by the lan- 
guage to be taken for an enabled condition in the 
absence of an on-unit for that condition. 


statement. A grouping of identifiers, constants, and 
delimiters that makes up do groups and blocks. The 
end of a statement is indicated by a semicolon (;). See 
also keyword statement, assignment statement, and null 
statement. 


statement body. A statement body can be either a 
simple or a compound statement. (1) A simple state- 
ment is a statement with a simple body. There are 
three types of simple statements: keyword, assignment 
and null. Each type contains a statement body that is 
terminated by a semicolon. (2) A compound statement 
begins with a keyword. All compound statements are 
keyword statements. There are four compound 
statements: IF, ON, WHEN, and OTHERWISE. A com- 
pound statement is terminated by a semicolon that also 
terminates the statement body. 


statement identifier. The PL/I keyword that indicates 
the purpose of a statement. 


statement-label constant. See /abel constant. 
statement-label expression. See /abe/ expression. 


statement-label variable. See /abel variable. 
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static storage allocation. The allocation of storage for 
Static variables. 


static variable. A variable that is allocated before exe- 
cution of the program begins and that remains allocated 
for the duration of execution. 


stream-oriented data transmission. The transmission 
of data in which the organization of the data into 
records is ignored and the data is treated as though it 
were a continuous stream of individual data values in 
character form. Contrast with record-oriented data 
transmission. 


string. (1) A series of things, such as characters, in a 
line. (2) In PL/I, a contiguous sequence of characters 
or bits that is treated as a single data item. (8) A group 
of auxiliary storage devices connected to a system. 

The order and location in which each device is con- 
nected to the system determines the physical address 
of the device. 


string variable. A variable declared with the BIT or 
CHARACTER attribute, whose values can be either bit 
strings or character strings. 


structure. A collection of data items that need not 
have identical attributes. Contrast with array. 


structure expression. An expression whose evalu- 
ation yields a structure set of values. 


structure of arrays. A structure containing arrays 
specified by declaring individual members names with 
the dimension attribute. 


structure members. Any of the minor structures or 
eiemeniary names in a structure. 


structuring. The makeup of a structure, in terms of 
the number of members, the order in which they 
appear, their attributes, and their logical level (but not 
necessarily their names or declared level numbers). 


structure variable. A variable that represents an 
aggregate of data items that might not have identical 
attributes. Contrast with array variable and scalar vari- 
able. 


subfield (of a picture specification). That portion of 
a picture specification field that appears before or after 
a V picture specification character. 


subroutine. A procedure that has no RETURNS 
option in the PROCEDURE statement. Contrast with 
function. 


subroutine call. An entry reference that must repre- 
sent a subroutine, followed by an optional and possibly 
empty argument list that appears in a CALL statement. 
Contrast with function reference. 
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subscript. An element expression that specifies a 
position within a dimension of an array. A subscript can 
also be an asterisk, in which case it specifies the entire 
extent of the dimension. 


- subscript list. A parenthesized list of one or more 


subscripts, one for each dimension of an array, which 
together uniquely identify either a single element or 
cross section of the array. 


synchronous. Using a single flow of control for serial 
execution of a program. 


T 


target reference. A reference that designates a gener- 
ation to receive an item of data. 


target variable. A variable to which a value is 
assigned. 


termination (of a block). Cessation of execution of a 
block, and the return of control to the activating block by 
means of a RETURN or END statement, or the transfer 
of control to the activating block or to some other active 
block by means of a GO TO statement. 


truncation. The removal of one or more digits, charac- 
ters, or bits from one end of an item of data when a 
String length or precision of a target variable has been 
exceeded. 


type. The set of data attributes and storage attributes 
that apply to a generation, a value, or an item of data. 


unconnected aggregate. See inherited dimensions. 


undefined. Indicates something that is not defined by 
the language and that may change without notice. Thus, 
programs that seem to work correctly when referencing 
undefined results do so by chance and are in error. 


union. A set of variants. 


upper bound. The upper limit of an array dimension. 


V 


value reference. A reference used to obtain the value 
of an item of data. 


variable. A named entity used to refer to data and to 
which values can be assigned. Its attributes remain 
constant, but it can refer to different values at different 
times. 


variable reference. A reference that designates all or Z 
part of a variable. 


virtual point picture character. The V picture specifi- zero-suppression charactors: The picture specifica- 
cation character, which is used in picture specifications tion characters Z and *, which are used to suppress 
to indicate the position of an assumed decimal or binary zeros in the corresponding digit positions and replace 
point. them with blanks or asterisks respectively. 
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Index 


Special Characters 

_ (underscore, break) 12 

, (insertion character) 292 

, (separator) 12, 15 

: (prefix, dimension, and range delimiter) 12, 15 
? (question mark) 12 

/ (division) 12, 15, 54 

/ (insertion character) 292 

/* */(comment) 15, 16 

. (insertion character) 292 

. (name qualifier, decimal point) 12, 15 
( ) (enclose symbols) 12, 15 

$ (picture character) 296 

* (multiplication) 12, 15, 54 

* zero suppression picture character 291 
** (exponentiation) 13, 15, 54 
*PROCESS statement 191 

& (and symbol) 12, 15 

& (bit operator: AND) 60 

% (for % statements) 12, 15 
%INCLUDE statement 187 
%NOPRINT statement 188 

%NOTE statement 188 

%PAGE statement 190 

%POP statement 190 

%PRINT statement 190 

%PROCESS statement 191 

%PUSH statement 191 

%SKIP statement 195 

— (subtraction) 12, 15, 54 

<= (less than or equal to symbol) 15, 61 
<= (less than or equal to) 13 

+ (addition) 12, 15, 54 

< (less than symbol) 12, 15, 61 

+ (picture character) 296 

>= (greater than or equal to symbol) 15 
>= (greater than or equal to) 13 

> (greater than symbol) 12, 15 

| (bit operator: OR) 60 

| (logical OR symbol) 12, 15 


Numerics 


9 picture specification character 287, 290 


A 

A picture specification character 287 
A-format item 274 

ABNORMAL attribute 217 

abnormal termination of a program 90 
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ABS built-in function 381 
accuracy of the mathematical built-in functions 373 
ACOS built-in function 382 
ACTIVATE 453 
activation 
begin block 111 
block 91 
procedure 98 
program 90 
AD/Cycle framework 3 
ADD built-in function 382 
additive attributes 
definition of 231 
ENVIRONMENT 235 
KEYED 235 
ADDR built-in function 383 
adjustable extents 
controlled 203 
aggregate 
assignments 168 
aggregate arguments 373 
aggregates 163 
algebraic comparison operations 61 
ALIGNED attribute 139 
alignment attributes for data 138 
ALL built-in function 383 
ALLOC (ALLOCATE) statement 202 
ALLOCATE statement (abbr: ALLOC) 202, 208 
for based variables 208 
for controlled variables 202 
IN option 208 
SET option 208 
allocation 198 
ALLOCATION built-in function (abbr: ALLOCN) 384 
alphabetic characters 10 
alphanumeric characters 11 
alternative attributes 230 
BUFFERED and UNBUFFERED 234 
definition of 230 
INPUT, OUTPUT, and UPDATE 233 
RECORD and STREAM 233 
SEQUENTIAL and DIRECT 234 
ANY built-in function 384 
application 
for PL/L 89 
area 
ALLOCATE statement with IN option 208 
assignment 214 
attributes 29 
data 211 
EMPTY built-in function 398 
input/output of 214 
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area (continued) 

transmission of variables 243 
AREA attribute 211 
AREA condition 312 
arguments 

aggregate 373 

argument lists 373 

dummy 109 

null list 373 

passing 

to procedures 108 
to the main procedure 110 

specifying how passed and received 123 
arithmetic built-in functions 374 

ABS 381 

CEIL 388 

COMPLEX 391 

CONJG 392 

FLOOR 402 

IMAG 407 

MAX 412 

MIN 413 

MOD 414 

RANDOM 429 

REAL 429 

REM 430 

ROUND 432 

SIGN 435 

TRUNC 444 
arithmetic character data 39, 43 

conversion to 80 

inserting editing characters 44 
arithmetic operations 54 

data conversion 55 

results 56 
arithmetic operators 15, 54 
arithmetic picture specification 38, 43 
array 

assignments 168 
array argument with parameters 

example 96 
array variable, definition of 144 
array-and-array operations 67 
array-and-element operations 67 
array-handling built-in functions 375 

ALL 383 

ANY 384 

DIMENSION 397 

HBOUND 404 

LBOUND 409 

PROD 428 

SUM 441 
arrays 

array-and-array operations 67 

array-and-element operations 67 

assignment 168, 169 


arrays (continued) 
attributes 29 
bounds of 144 
cross sections of 147 
definition of 144 
DIMENSION attribute 144 
examples 145 
expression 51, 66 
extent 144 
infix operators and 67 
of structures/unions 153 
prefix operators and 67 
subscripts of 146 
targets 168 
ASIN built-in function 384 
ASM (ASSEMBLER) option 123 
ASSEMBLER (abbr: ASM) option 123 
ASSIGNABLE attribute 216 
assignment 454 
area 214 
assignment statement 18, 167 
BY NAME option 167 
requirements for target variables 168 
assignments 
aggregate 168 
array 168, 169 
element 168 
how performed 168 
multiple 170 
structure 168 . 
association of arguments and parameters 108 
asterisk 14, 291 
arithmetic operators 54 
as identifiers 14 
use for a subscript 147 


’ ATAN built-in function 385 


ATAND built-in function 385 
ATANH built-in function 386 
ATTENTION condition (abbr: ATTN) 313 
ATTN (ATTENTION) condition 313 
attributes 25 

ABNORMAL 217 

additive 231 

ALIGNED 139 

alternative 230 

area 29 

array data 29 

ASSIGNABLE 216 

AUTOMATIC 200 

BINARY 31 

BIT 37 

BUFFERED 234 

BUILTIN 371 

BYADDR 123 

BYVALUE 123 

CHARACTER 37 
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attributes (continued) 
CHARGRAPHIC 123 
classification according to data types 27 
coded arithmetic 28, 29 
COMPLEX 32 
computational data 25 
CONDITION 310 
CONNECTED 217 
CONTROLLED 201 
data 25, 26 
DECIMAL 31 
defaults for data 141 
DEFINED 218 
descriptive 26 
DIMENSION 144 
DIRECT 234 
entry 28, 29, 114 
ENVIRONMENT 235 
EXTERNAL 134 
FETCHABLE 
FILE 230 
file data 28, 29 
FIXED 31 
FLOAT 31 
for parameters 95 
FORMAT 29, 47 
GENERIC 118 
GRAPHIC 37 
INITIAL 220 
INPUT 233 
INTERNAL 134 
KEYED 235 
LABEL 46 
label data 29 
LIKE 151 
LIMITED 117 


I +. ant fale’ 
;ocalor Gala cy 


merging of 238 

named coded arithmetic 28 
named string data 28 
NOCHARGRAPHIC 123 
non-data 27 
NONASSIGNABLE 216 
NONCONNECTED 217 
NORMAL 217 
OPTIONAL 116 
OPTIONS 121 

OUTPUT 233 
PARAMETER 95 
PICTURE 38 

picture data 29 
PRECISION 32 t 
PRINT 270 

program control data 26 
REAL 32 

RECORD 233 
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attributes (continued) 

RESERVED 138 
SEQUENTIAL 234 

SIGNED 33 

STATIC 199 

STREAM 233 

String data 28, 29 

structure data 30 
UNALIGNED 139 
-UNBUFFERED 234 

UNION 149 

union data 30 

UNSIGNED 33 

UPDATE 233 

VALUE 45 

VARIABLE 48 

VARYING 38 
AUTO (AUTOMATIC) attribute 200 
AUTOMATIC attribute (abbr: AUTO) 200 
automatic storage 198, 200 
automatic variables, effect of recursion on 101 


B (insertion character) 292 
B-format item 274 
B4 (bit hex) bit string constant 41 
BASED attribute 204 
based storage 198, 204 
based variables 204, 208 
ALLOCATE statement 208 
FREE statement 209 
input/output of lists 214 
begin block 
termination 111 
begin blocks 111 


TINE atat + 444 
BEGIN statement 111 


valid OPTIONS options for 121 
BINARY attribute (abbr: BIN) 31 
BINARY built-in function (abbr: BIN) 386 
binary fixed-point constant 34 
binary fixed-point data 34 

conversion to 78 
binary floating-point data 36 

conversion to 79 
BINARYVALUE built-in function 54, 387 
bit 

conversion to 72, 83 

data 41 

format item 274 

operators 15, 60 
BIT attribute 37 
BIT built-in function 387 
bit constant 41 
bit operations 

examples 61 


bit strings, transmission of unaligned 242 
BKWD environment characteristic 235 
blanks 15, 16 
blocks 91 

activation 91 

begin 111 

packages 92 

procedures 94 

termination 92 

types of 91 
books, PL/I and Language Environment 4 
BOOL built-in function 387 
Boolean operators 60 
bounds, definition of 144 
break (_) character, punctuating constants with 25 
BUF (BUFFERED) attribute 234 
BUFFERED attribute (abbr: BUF) 234 
built-in functions 371 

ABS 381 

accuracy of mathematical functions 373 

ACOS 382 

ADD 382 

ADDR 383 

ALL 383 

ALLOCATION 384 

and aggregate arguments 373 

and null argument lists 373 

ANY 384 

arithmetic 374 

array-handling 375 

ASIN 384 

ATAN 385 

ATAND 385 

ATANH 386 

BINARY 386 

BINARYVALUE 54, 387 

BIT 387 

BOOL 387 

CEIL 388 

CENTERLEFT 388 

CENTERRIGHT 389 

CHARACTER 390 

COLLATE 391 

COMMENT 459 

COMPARE 391 

COMPILETIME 460 

COMPLEX 391 

computational datac 73 

condition-handling 375 

CONJG 392 

COPY 392 

COS 393 

COSD 393 

COSH 393 

COTAN 393 

COTAND 394 


built-in functions (continued) 


COUNT 394 
COUNTER 460 
CURRENTSIZE 394 
CURRENTSTORAGE 395 
DATAFIELD 395 
DATE 396 
date/time 375 
DATETIME 396 
DECIMAL 397 
definition 108 
DIMENSION 397 
DIVIDE 397 
EMPTY 398 
ENDFILE 398 
ENTRYADDR 399 
EPSILON 399 
ERF 399 

ERFC 400 

EXP 400 
EXPONENT 400 
FILEOPEN 401 
FIXED 401 

FLOAT 401 
floating-point inquiry 376 
floating-point manipulation 376 
FLOOR 402 

for controlled variables 203 
GAMMA 402 
GRAPHIC 403 
HBOUND 404 
HEX 404 
HEXIMAGE 405 
HIGH 406 

HUGE 406 

IAND 406 

IEOR 407 

IMAG 407 

INDEX 407 
input/output 376 
integer manipulation 377 
1IOR 408 

LBOUND 409 
LEFT 409 
LENGTH 409 
LINENO 410 

LOG 410 

LOG10 411 

LOG2 411 
LOGGAMMA 410 
LOW 411 
LOWER2 411 
macro facility 458 
mathematical 377 
MAX 412 
MAXEXP 412 
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built-in functions (continued) 
MAXLENGTH 413 
MIN 413 
MINEXP 414 
miscellaneous 378 
MOD 414 
MPSTR 415 
MULTIPLY 416 
NULL 416 
OFFSET 416 
OFFSETADD 417 
OFFSETDIFF 417 
OFFSETSUBTRACT 417 
OFFSETVALUE 418 
OMITTED 418 
ONCHAR 418 
ONCODE 419 
ONCOUNT 419 
ONFEEDBACK 
ONFILE 420 
ONGSOURCE 420 
ONKEY 421 
ONLOC 421 
ONSOURCE 422 
PAGENO 423 
PLACES 423 
PLIRETV 425 
POINTER 425 
POINTERADD 54, 426 
POINTERDIFF 426 
POINTERSUBTRACT 427 
POINTERVALUE 54, 427 
PRECISION 427 
precision-handling 378 
PRED 428 
PROD 428 


MINT Ana 
WUNIioC +01 


RADIX 428 
RAISE2 429 
RANDOM 429 
REAL 429 
REM 430 
REPEAT 430 
REVERSE 431 
RIGHT 431 
ROUND 432 
SAMEKEY 433 
SCALE 433 
SEARCH 433 
SEARCHR 434 
SIGN 435 
SIGNED 435 
SIN 435 
SIND 436 
SINH 436 
SIZE 436 
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built-in functions (continued) 
SQRT 437 
STORAGE 438 
storage control 379 
STRING 438 
string-handling 380 
subroutines 381 
SUBSTR 439 
SUBTRACT 440 
SUCC 440 
SUM 441 
SYSPARM 461 
SYSTEM 462 
SYSVERSION 462 
TAN 441 
TAND 441 
TANH 442 
TIME 442 
TINY 442 
TRANSLATE 442 
TRIM 443 
TRUNC 444 
UNSIGNED 444 
UNSPEC 445 
VALID 447 
VERIFY 447 
VERIFYR 448 
built-in names 106, 108 
built-in pseudovariables 379 
built-in subroutines 106, 381 
PLIDUMP 423 
PLIFILL 424 
PLIMOVE 424 
PLIRETC 425 
BUILTIN attribute 371 
BX (bit hex) string constant 41 
BY NAME option of assignment statement 167 
when not specified in structure assignment 169 
when specified in structure assignment 169 
BY option of DO statement 175 
BYADDR attribute 123 
byte 138 
BYVALUE attribute 123 


C 


C language 

FINISH condition 318 
C-format item 275 
CALL option on INITIAL attribute 222 
CALL statement 120 
case sensitivity 13 
CEIL built-in function 388 
CENTERLEFT built-in function 388 
CENTERRIGHT built-in function 389 


CENTRELEFT 

See PARM 
CENTRERIGHT 

See string-handling built-in functions, 

CENTERRIGHT 

CHAR (CHARACTER) attribute 37 
CHARACTER attribute (abbr: CHAR) 37 
CHARACTER built-in function (abbr: CHAR) 390 
CHARACTER macro facility variables 453 
character string constant 40 
characters 

alphabetic 10 

alphanumeric 11 

character data 39 

conversion to 72, 81, 85 
picture specifiers for 287 

comparison operations 62 

constant 39, 41, 43 

extralingual 10 

format item 274 

picture specification 38 


sets 
double-byte 19 
single-byte 10 
special 12 


CLOSE statement 239 
COBOL option 124 
coded arithmetic data 
attributes 25, 28, 29 
abbreviations 31 
BINARY and DECIMAL attributes 31 
binary fixed-point data 34 
binary floating-point 36 
conversion 72, 85 
conversion to 77 
decimal fixed-point 35 
decimal floating-point 36 
FIXED and FLOAT attribute 31 
PRECISION attribute 32 
REAL and COMPLEX attributes 32 
complex data item 32 
real data item 32 
variable representing complex data items 32 
syntax 31 
COLLATE built-in function 391 
colon symbol 15 
COLUMN format item 276 
combinations of operations 64 
comma 15 
COMMENT built-in function 459 
comments 15, 16 
COMPARE built-in function 391 
comparison operations 
algebraic 61 
bit 62 
character 62 


comparison operations (continued) 
conversion of operands in 61 
graphic 62 
pointer and offset data 62 
program control data 62 
comparison operators 15 
compilation unit 89 
COMPLEX attribute (abbr: CPLX) 32 
COMPLEX built-in function (abbr: CPLX) 391 
complex format item 275 
composite symbols 13 
compound statements 18 
computational conditions 
CONVERSION 315 
FIXEDOVERFLOW 319. 
INVALIDOP 320 
OVERFLOW 322 
SIZE 323 
UNDERFLOW 328 
ZERODIVIDE 329 
computational data 
attributes 25 
coded arithmetic data 25 
conversion 73 
string data 25 
concatenation operations 63 
concatenation operators 15 
COND (CONDITION) condition 314 
CONDITION attribute 310 
condition codes 302, 329, 419 
CONDITION condition (abbr: COND) 314 
condition handling 302 
CONDITION attribute 310 
enabling/disabling 302 
established action 305 
multiple conditions 309 
ON statement 305 
dynamically-descendant ON-units 307 
null ON-unit 306 
ON-units for file variables 307 
scope of established action 306 
RESIGNAL statement 309 
REVERT statement 308 
scope of condition prefix 304 
SIGNAL statement 309 
condition prefix 17, 302 
condition-handling built-in functions 375 
DATAFIELD 395 
ONCHAR 418 
ONCODE 419 
ONCOUNT 419 
ONFEEDBACK 
ONFILE 420 
ONGSOURCE 420 
ONKEY 421 
ONLOC 421 
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condition-handling built-in functions (continued) 

ONSOURCE 422 
conditions 312, 329 

AREA 312 

ATTENTION 313 

computational 303 

CONDITION 314 

CONVERSION 315 

ENDFILE 316 

ENDPAGE 317 

ERROR 318 

FINISH 318 

FIXEDOVERFLOW 319 

input/output 303 

INVALIDOP 320 

KEY 320 

miscellaneous 303 

NAME 321 

OVERFLOW 322 

program checkout 303 

raising under OPTIMIZATION 305 

RECORD 322 

SIZE 323 

status of 303 

STORAGE 324 

STRINGRANGE 324 

STRINGSIZE 325 

SUBCRIPTRANGE 326 

TRANSMIT 326 

UNDEFINEDFILE 327 

UNDERFLOW 328 

ZERODIVIDE 329 
CONJG built-in function 392 
CONNECTED attribute (abbr: CONN) 217 
connected storage 217 
consecutive data sets 229 
CONSECUTIVE environment charac 
constants 

B4 (bit hex) string 41 

B4 string 41 

bit 41 

BX string 41 

character 39, 41, 43 

character string 40 

definition 24 

entry 112 

file 230 

graphic 42 

GX (graphic) string 42 

imaginary 32 

M (mixed) string 43 

named 24 

XN (binary hex) 34 

Z (null-terminated) character string 40 
contained in, definition 132 
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contextual declarations 131 
continuation rules for DBCS 21 
control 
of storage 198 
control (%) statements 
DCL (DEACTIVATE) 454 
DCL (DECLARE) 455 
DEACTIVATE 454 
DECLARE 455 
DO 455 
END 456 
GOTO 456 
INCLUDE 457 
null 458 
controlled 
storage 198, 201 
structures 203 
variables 201 
ALLOCATE statement 202 
FREE statement 202 
multiple generations of 203 
CONTROLLED attribute (abbr: CTL) 201 
CONV (CONVERSION) condition 315 
conversion 72 
arithmetic operations 55 
arithmetic precision 75 
built-in functions 73 
in concatenation operations 63 
mode 75 
operands 56 
source to target rules 77, 84 
String lengths 74 
to other data attributes 75 
CONVERSION condition (abbr: CONV) 315 
CONVERSION condition prefix 303 
COPY built-in function 392 
COPY option 254 
corresponding data sets 229 
COS built-in function 393 
COSD built-in function 393 
COSH built-in function 393 
COTAN built-in function 393 
COTAND built-in function 394 
COUNT built-in function 394 
COUNTER macro facility built-in function 460 
CPLX (COMPLEX) attribute 32 
CPLX (COMPLEX) built-in function 391 
credit (CR) picture character 298 
cross sections of arrays 147 
cross sections of arrays of structures/unions 154 
CTL (CONTROLLED) attribute 201 
CTLASA environment characteristic 235 
currency symbol 296 
CURRENTSIZE built-in function 394 
CURRENTSTORAGE built-in function 395 


D 


data 
aggregates 24, 163 
alignment of 138 
arithmetic character 43 
attributes 25, 26 
B4 (bit hex) bit string constant 41 
binary fixed-point 34 
binary floating-point 36 
bit 41 
bit constant 41 
BX (bit hex) string constant 41 
character 39 
character constant 39 
computational 25 
conversion 72, 85 
decimal fixed-point 35 
decimal floating point 36 
elements 24 
entry 112 
format items 274 
graphic 42 
items 24 
label 46 
mixed 42 
numeric character 288 
program control 26 

types and attributes 46 

specifications 254 
transmission 228 
types 25 
X (Hex) character string constant 40 

data conversion 55 

data declaration 128 
array 144 
explicit 128 
implicit 131 
structure 147 
union 149 

data items 
aggregates 24 
definition 24 
expression 51 
scalar 24 

data sets 228, 229 
consecutive 229 
direct 229 
indexed 229 
regional 230 
relative 229 

data specification options for stream i/o 254 
data transmitted 242 
data-directed 259 
definition of 252 
edit-directed 263 


a dN 


data specification options for siream i/o (conitiriuiéa) 
list-directed 267 
repetitive specification 255 
transmission of data list items 259 
data transmission 242 
area variables 243 
data aggregates 242 
data-directed 252 
edit-directed 252 
graphic strings 242 
input 228, 240 
of data-list-items 259 
output 228, 240 
record-oriented 228, 242 
record-oriented statements 243, 252 
DELETE 245 
LOCATE 245 
READ 243 
REWRITE 244 
WRITE 244 
stream-oriented 228, 252 
stream-oriented statements 252 
GET 253 
PUT 253 
TRANSMIT condition 326 
unaligned bit strings 242 
varying length strings 242 
data transmission statements options 254 
COPY 254 
FILE 256 
LINE 256 
PAGE 256 
SKIP 257 
STRING 257 
data-directed data 260 
syntax of 260 
data-directed data specification 259 
GET 261 
PUT 262 
data-directed data transmission 252 
DATAFIELD built-in function 395 
DATE built-in function 396 
date/time built-in functions 375 
DATE 396 
DATETIME 396 
TIME 442 
DATETIME built-in function 396 
DB (debit) picture character 298 
DBCS (double-byte character set) 19 
continuation rules 21 
elements 20 
identifiers, uses for 20 
DCL (DECLARE) statement 129 
debit (DB) picture character 298 
DECIMAL attribute (abbr: DEC) 31 
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DECIMAL built-in function (abbr: DEC) 397 
decimal fixed-point data 35 
conversion to 78 
decimal floating-point data 36 
conversion to 79 
decimal-point and digit specifiers 290 
declarations 
array 144 
contextual 131 — 
explicit 128 
implicit 131 
scope of 132 
DECLARE statement (abbr: DCL) 129 
declaring data 128 
factoring of attributes 130 
DEF (DEFINED) attribute 218, 219 
DEFAULT statement (abbr: DFT) 142 
defaults for attributes 141 
DEFAULT statement 142 
for data attributes 141 
language-specified 141 
restoring language-specified 144 
DEFINED attribute (abbr: DEF) 218, 219 
DELAY statement 172 
DELETE statement 245 
delimiters 15 
descriptive attributes 26 
descriptor list, parameter 114 
DESCRIPTOR option 124 
DFT (DEFAULT) statement 142 
digits 
and decimal-point specifiers 290 
binary 12 
decimal 11 
hexadecimal 12 
DIM (DIMENSION) attribute 144 
DIMENSION attribute (abbr: DIM) 144 
DIMENSION built-in function (abbr: DIM) 397 
DIRECT attribute 234 
direct data set 229 
direct entry declaration 112 
DISPLAY statement 172 
DIVIDE built-in function 397 
DLL (file extension) 
with load modules 89 
DO statement 173 
do-groups 173 
examples 179 
type 3 do-group 174, 176 
double-byte character set (DBCS) 19 
continuation rules 21 
data in stream i/o 272 
elements 20 
identifiers, uses for 20 
using in source program 19 
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doubleword 138 
drifting character 296 
dummy arguments 109 
rules 110 
dynamic allocation 198 
dynamic loading of an external procedure 101 
dynamically-descendant ON-units 307 


E 


E picture character 298 
E-format item 276 
EDIT option 263 
edit-directed . 

data specification 263 

data transmission 252 

format items 274 
effect of recursion on automatic variables 101 
elementary names 147 
elements 

assignment 168 

data 24 

DBCS 20 

expression 51 

parameter 110 

program 10 

Scalar 24 

statement 14 

variable 24 
ELSE clause of %IF statement 456 
ELSE clause of IF statement 185 
EMPTY built-in function 398 
enabled condition 302, 304 
END statement 183 
ENDFILE built-in function 398 
ENDFILE condition 316 
ENDPAGE condition 317 
ENTRY attribute 114 

valid OPTIONS options for 122 
entry data 112 

attributes 28, 29 

constants 112 

direct entry declaration 112 

generic entry declaration 118 

invocation of references 120 

variables 113 
entry points 94 
entry reference invocation 120 
ENTRYADDR built-in function 399 
ENTRYADDR pseudovariable 399 
ENV (ENVIRONMENT) attribute 235 
ENVIRONMENT attribute (abbr: ENV) 235 
EPSILON built-in function 399 
equal sign 15 
ERF built-in function 399 


ERFC built-in function 400 
ERROR condition 318 
established action 305 
established condition 302, 304 
evaluation order for expressions and references 65 
evaluation order of expressions 52 
EXE (file extension) 

with load modules 89 
EXP built-in function 400 
explicit declaration 128 
explicitly locator-qualified reference 206 
EXPONENT built-in function 400 
exponent specifiers 298 
exponentiation, special cases for 59 
expressions 50 

array 51, 66 

element 51 

evaluation order 52 

of targets 52 

operational 50, 53° 

restricted 68 

scalar 51 

Structure 51 

syntax 50 - 
EXT (EXTERNAL) attribute 134 
extent (of bounds) 144 
EXTERNAL attribute (abbr: EXT) 134 
external procedure 

definition of 94 

dynamic loading of 101 
extralingual characters 10 


F 


F picture character 299 
F-format item 278 
factoring of attributes 130 
FETCH statement 103 
FETCHABLE attribute 
restrictions 102 
fields 289 
file 
option of data transmission statements 
record-oriented data transmission 245 
reference 
specifying 233 
FILE attribute 230 
FILE option 256 
stream-oriented data transmission 243 
FILE specification in OPEN statement 236 
FILEOPEN built-in function 401 
filles 230 
additive attribute 231 
alternative attributes 230 
attributes 28, 29 
constant 230 


tiles (continuea) 
declaration 230 
definition of 228, 230 
describing a file constant 230 
describing a file variable 232 
description attributes 230 
FILE attribute 230 
implicit opening 237 
opening and closing 235 
PRINT 270 
variable 232 
FINISH condition 318 
FIXED attribute 31 
FIXED built-in function 401 
FIXED macro facility variables 453 
fixed-point 
binary data 34 
decimal data 35 
format item 278 
FIXEDOVERFLOW condition (abbr: FOFL) 319 
FIXEDOVERFLOW condition prefix 303 
FLOAT attribute 31 
FLOAT built-in function 401 
floating-point 
binary data 36 
data conversion 79 
decimal data 36 
format item 276 
inquiry built-in functions 376 
EPSILON 399 
HUGE 406 
MAXEXP 412 
MINEXP 414 
PLACES 423 
RADIX 428 
TINY 442 
manipulation built-in functions 376 
EXPONENT 400 
PRED 428 
SCALE 433 
SUCC 440 
FLOOR built-in function 402 
FOFL (FIXEDOVERFLOW) condition 319 
FORMAT attribute 29, 47 
format data 47 
format items 264 
A 274 
B 274 
C 275 
COLUMN 276 
E 276 
F 278 
G 280 
L 281 
LINE 281 
P 282 
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format items (continued) 
PAGE 282 
R 282 
SKIP 283 
X 284 
FORMAT statement 267 
FORTRAN option 124 
FREE statement 202, 209 
for based variables 209 
for controlled variables 202 
IN option 209 
FROM 
option of data transmission statements 246 
fullword 138 
functions 106, 120 
See also built-in functions 
definition 106 
examples 107 
returning from 121 


G 


G (GRAPHIC) attribute 37 
G-format item 280 
GAMMA built-in function 402 
GENERIC attribute 118 
generic entry declaration 118 
generic name 118 
generic selection 119 
GENKEY environment characteristic 235 
GET statement 
data-directed 261 
edit-directed 265 
list-directed 268 
strings 265 
GET STRING statement 253 
GO TO statement (abbr: GOTO) 184 
GRAPHIC attribute (abbr: G) 37 
GRAPHIC built-in function 403 
graphic constant 42 
comparison operations 62 
format item 280 
Strings 242 
graphic conversion 390 
graphic data 42 
conversion to 84 
graphic constant 42 
GX (graphic hex) string constant 42 
transmission 242 
GRAPHIC environment characteristic 235 
graphic string constant 42 
groups 
of statements 19 
GX (graphic hex) string constant 42 
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H 


halfword 138 

HBOUND built-in function 404 

hex (X) character string constant 40 
HEX built-in function 404 
HEXIMAGE built-in function 405 
HIGH built-in function 406 

HUGE built-in function 406 


I 
IAND built-in function 406 
identifiers 
asterisk 14 
DBCS 19 
DBCS with double-byte characters 20 
definition 14 
keywords 14 
programmer-defined names 14 
single-byte in DBCS form 20 
IEOR built-in function 407 
IF statement 185 
IGNORE 
option of data transmission statements 246 
IMAG built-in function 407 
IMAG pseudovariable 407 
imaginary constant 32 
implementation limits 465 
implicit 
declaration 131 
freeing 203 
opening of files 237 
implicit action 302, 304 
implicitly locator-qualified reference 207 
IN option 
ALLOCATE statement 208 
FREE statement 209 
IN option with FREE statement 
for based variables 209 
INDEX built-in function 407 
indexed data sets 229 
industry standards 6 
infix operation 53 
infix operators and arrays 67 
INITIAL attribute (abbr: INIT) 220 
initial value 220 
on STATIC variables 223 
initializing 
array variables 222 
automatic variables 224 
based and controlled variables 224 
Static variables 223 
unions 223 
input and output 228, 240 
built-in functions 376 
COUNT 394 


input and output (continued) 
built-in functions (continued) 
ENDFILE 398 
FILEOPEN 401 
LINENO 410 
PAGENO 423 
SAMEKEY 433 
conditions 
ENDFILE 316 
ENDPAGE 317 
KEY 320 
NAME 321 
RECORD 322 
TRANSMIT 326 
UNDEFINEDFILE 327 
of area 214 
INPUT attribute 233 
input, definition of 228 
insertion characters 292 
INT (INTERNAL) attribute 134 
integer 
definition of 11, 12 
restricted 219 
integer manipulation built-in functions 377 
IAND 406 
IEOR 407 
lIOR 408 
LOWER2 411 
RAISE2 429 
integer value, definition 32 
integral boundary 138 
interleaved subscripts 154 
intermediate results of expressions 53 
example 59 
INTERNAL attribute (abbr: INT) 134 
internal procedure 94 
internal to, definition 132 
INTO 
option of data transmission statements 247 
INVALIDOP condition 320 
INVALIDOP condition prefix 303 
invocation of entry references 120 
invoked procedure 98 
invoking block 98 
IOR built-in function 408 
IRREDUCIBLE option (abbr: IRRED) 125 
ITERATE statement 187 


K 


K picture character 298 
KEY 
option of data transmission statements 247 
KEY condition 320 
KEYED attribute 235 


KEYFROM 

option of data transmission statements 247 
KEYLENGTH environment characteristic 235 
KEYLOC environment characteristic 235 
KEYTO 

option of data transmission statements 248 
keyword statements 18 
keywords 14 

macro facility 452 


L 


L format item 281 
LABEL attribute 46 
valid OPTIONS options for 46 
label data 46 
attributes 29 
label prefixes 
syntax 
labels 
on language statements 18, 46 
language-specified defaults 141 
defining 141 
restoring 144 
LBOUND built-in function 409 
LEAVE statement 187 
LEFT built-in function 409 
LENGTH built-in function 409 
level number (of structure elements) 155 
levels of structures 147, 149 
levels of unions 149 
LIKE attribute 151 
LIMITED attribute 117 
limits 465 
LINE format item 281 
LINE option 256 
LINENO built-in function 410 
LINESIZE specification in OPEN statement 237 
LINKAGE option 124 
list 
bidirectional 216 
chained 215 
processing 215 
unidirectional 216 
list-directed 
data specification 267 
data transmission 252 
GET statement 268 
input 268 
output 269 
PUT statement 269 
list, parameter descriptor 114 
listing control statements 450 
load module 89 
locate mode 249 
definition of 249 
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LOCATE statement 245 
locator 

conversion 205 

levels of qualification 207 

qualification 206 

qualifier 15 

reference 206 
locator data 205 

attributes 29 

offset variable 205 

pointer variable 205 

qualification 206 
locator parameter 110 
LOG built-in function 410 
LOG10 built-in function 411 
LOG2 built-in function 411 
LOGGAMMA built-in function 410 
logical level (of structure elements) 155 
logical operators 15, 60 
LOW built-in function 411 
LOWER2 built-in function 411 


M (mixed) string constant 43 
macro facility 450 
built-in functions 458 
expressions 453 
input 450 
input text 450 
keywords 452 
output 450 
scan 450 
statements 450 
statements, list of 453 
variables 453 
CHARACTER data type 453 
data types 453 
FIXED data type 453 
replacement 451 
macro facility statements 453 
scanning 450 
MAIN option 125 
main procedure 90 
passing an argument to 110 
major structure names 147 
mathematical built-in functions 377 
accuracy of 373 
ACOS 382 
ASIN 384 
ATAN 385 
ATAND 385 
ATANH 386 
COS 393 
COSD 393 
COSH 393 


496 PL/I Package/2 Language Reference 


mathematical built-in functions (continued) 
COTAN 393 

COTAND 394 

ERF 399 

ERFC 400 

EXP 400 

GAMMA 402 

LOG 410 

“LOG10 411 

LOG2 411 

LOGGAMMA 410 

SIN 435 

SIND 436 

SINH 436 

SQRT 437 

TAN 441 

TAND 441 

TANH 442 
MAX built-in function 412 
MAXEXP built-in function 412 
MAXLENGTH built-in function 413 
MIN built-in function 413 
MINEXP built-in function 414 
minor structure names 147 
miscellaneous built-in functions 378 
COLLATE 391 
COMPARE 391 

HEX 404 

HEXIMAGE 405 
OMITTED 418 

PLIRETV 425 

STRING 438 
miscellaneous conditions 
AREA 312 

ATTENTION 313 
CONDITION 314 
ERROR Sid 

FINISH 318 

STORAGE 324 
UNSPEC 445 

VALID 447 
mixed data 42 
MOD built-in function 414 
modes of processing 249 
locate 249 

move 249 
move mode 249 
MPSTR built-in function 415 
multiple assignment 170 
multiple conditions 309 
multiple generations of controlled variables 203 
MULTIPLY built-in function 416 


N 
NAME condition 321 
named coded arithmetic data 

attributes 28 
named constants 24 

example 45° 
named string data 

attributes 28 
NODESCRIPTOR option 124 
NOEXECOPS option 125 
non-data attributes 27 
NONASSIGNABLE attribute 216 
NONCONNECTED attribute (abbr: NONCONN) 217 
nonconnected storage 147 
NONVAR (NONVARYING) attribute 38 
NONVARYING attribute (abbr: NONVAR) 38 
NOPRINT statement 188 
NORMAL attribute 217 
normal termination of a program 90 
NOTE statement 188 
NULL built-in function 416 
null ON-unit 306 
null statement 18, 189 
null-terminated character string constant 40 
numeric character data 

See also arithmetic character data 

See also PARM 

conversion to 72, 80, 85 

definition 43 

picture specifiers for 288 
numeric character pictured item 286, 289 


O 


OFFSET attribute 213 
OFFSET built-in function 416 
offset data 213 
offset variable 205 
OFFSETADD built-in function 417 
OFFSETDIFF built-in function 417 
OFFSETSUBTRACT built-in function 417 
OFFSETVALUE built-in function 418 
OFL (OVERFLOW) condition 322 
OMITTED built-in function 418 
ON statement 305 
ON-units 305 
dynamically-descendant 307 
for file variables 307 
null 306 
scope 306 
ONCHAR built-in function 418 
ONCHAR pseudovariable 419 
ONCODE built-in function 302, 419 
ONCOUNT built-in function 419 


ONFEEDBACK buiit-in tunciion 
ONFILE built-in function 420 
ONGSOURCE built-in function 420 
ONGSOURCE pseudovariable 420 
ONKEY built-in function 421 
ONLOC built-in function 421 
ONSOURCE built-in function 422 
ONSOURCE pseudovariable 422 
OPEN statement 236 
opening and closing files 235 
operands 50 

conversion 56 
operational expressions 50, 53 
operations 

arithmetic 54 

bit 60 

combinations of 64 

comparison 61 

concatenation 63 

infix 53 

logical 60 

pointer 54 

pointer support extensions with 54 

prefix 53 
operators 15 

arithmetic 15, 54 

bit 15 

comparison 15 

infix 67 

logical 15 

string 15 
OPTIMIZATION, raising conditions under 305 
OPTIONAL attribute 116 
OPTIONS attribute 121 
options of data transmission statements 245, 254 
OPTIONS options 121 

ASSEMBLER 123 

BYADDR 123 

BYVALUE 123 

characteristic-list . 121 

CHARGRAPHIC 123 

COBOL 124 

DESCRIPTOR 124 

FETCHABLE 

for BEGIN statement 121 

for ENTRY declaration 122 

for PROCEDURE statements 122 

FORTRAN 124 

IRREDUCIBLE 125 

LINKAGE 124 

MAIN 125 

NOCHARGRAPHIC 123 

NODESCRIPTOR 124 

NOEXECOPS 125 

ORDER 125 

RECURSIVE 100 
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OPTIONS options (continued) 

REDUCIBLE 125 

REENTRANT 125 

REORDER 125 

RETCODE 125 

WINPROC 126 
order of evaluation 65 
ORDER option 125 
ORGANIZATION environment characteristic 235 
OTHERWISE option of GENERIC attribute 118 
OTHERWISE option of SELECT statement 193 
output and input 228, 240 

built-in functions 376 

conditions 303 

of area 214 
OUTPUT attribute 233 
output, definition of 228 
OVERFLOW condition (abbr: OFL) 322 
OVERFLOW condition prefix 303 


p 


P-format item 282, 286 
PACKAGE statement 92 

valid OPTIONS options for 122 
packages 92 
PAGE format item 282 
PAGE option 256 
PAGE statement 190 
PAGENO built-in function 423 
PAGESIZE specification in OPEN statement 237 
PARAMETER attribute 95 
parameter descriptor list 114 
parameters 

and arguments 108 

and array arguments 96 

example 96 

element 110 

locator 110 
parentheses 15 
passing an argument 

to the main procedure 110 
passing an argument to the MAIN procedure 110 
passing arguments 108 

by BYVALUE and BYADDR_ 109 
percent symbol 15 
period 15 
PIC (PICTURE) attribute 38 
PICTURE attribute (abbr: PIC) 38 
picture data 

attributes 29 

format item 282 

repetition factors 286 

scaling factor 299 

specification 38 

specifiers for character data 287 
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picture data (continued) 
specifiers for numeric character data 288 
syntax for PICTURE attribute 38 
picture specification characters 286 
, 292 
/ 292 
. 292 
$ 295 
* 291 
— 296 
+ 296 
9 290 
B 292 
CR 298 
DB 298 
298 
299 
298 
296 
290, 293 
298 
291 
PL/I Package/2 
publications 4 
PLACES built-in function 423 
PLIDUMP built-in subroutine 423 
PLIFILL built-in subroutine 424 
PLIMOVE built-in subroutine 424 
PLIRETC subroutine 425 
PLIRETV built-in function 425 
point of invocation 98 
POINTER attribute (abbr: PTR) 208 
POINTER built-in function (abbr: PTR) 425 
pointer operations 54 
pointer symbol 15 
pointer variable 205, 208 
POINTERADD built-in function (abbr: P 
426 . 
POINTERDIFF built-in functions 426 
POINTERSUBTRACT built-in functions 427 
POINTERVALUE built-in function (abbr: 
PTRVALUE) 54, 427 
POP statement 190 
POS (POSITION) attribute 218 
POSITION attribute (abbr: POS) 218 
PRECISION attribute 32 
PRECISION built-in function (abbr: PREC) 427 
precision-handling built-in functions 378 
ADD 382 
BINARY 386 
DECIMAL 397 
DIVIDE 397 
FIXED 401 
FLOAT 401 
MULTIPLY 416 
PRECISION 427 
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precision-handling built-in functions (continued) 
SIGNED 435 
SUBTRACT 440 
UNSIGNED 444 
PRED built-in-functions 428 
prefix operation 53 
prefixes, condition 302 
PRINT attribute 270 
PRINT statement 190 
priority of operators 65 
PROC (PROCEDURE) statement 94 
PROCEDURE statement (abbr: PROC) 90, 94 
valid OPTIONS options for 122 
procedures 94 
activation 98 
blocks 91 
dynamic loading 101 
passing an argument to main 110 
passing arguments 108 
recursive 100 
termination 99 
PROCESS statement 191 
processing modes 249 
locate 249 
move 249 
processing, list 215 
PROD built-in function 428 
program 10, 89 
activation 90 
definition of (for PL/I) 89 
structure 89 
termination 90 
program block definition 89 
program control data 26 
program organization 89 
program-checkout conditions 
STRINGRANGE 324 
STRINGSIZE 325 
SUBSCRIPTRANGE 326 
programmer-defined names 14 
pseudovariables 371, 379 
definition 52 
ENTRYADDR 399 
IMAG 407 
ONCHAR 419 
ONGSOURCE 420 
ONSOURCE 422 
REAL 430 
STRING 439 
' SUBSTR 440 
UNSPEC 446 
PTR (POINTER) attribute 208 
PTR (POINTER) built-in function 425 
PTRADD (POINTERADD) built-in function 54, 426 
PTRVALUE (POINTERVALUE) built-in function 54, 
427 


publications, PL/I Package/2 4 
punctuating constants 25 
PUSH statement 191 
PUT statement 
data-directed 262 
edit-directed 266 
list-directed 269 
STREAM output 253 
strings 266 


Q 


qualification 
locator 206 
structure 150 
unions 150 
qualified reference 150 
quotation marks 25 
using in strings 25 
QUOTE macro facility built-in function 461 
quote, double 12, 15 
quote, single 15 


R 


R-format item 282 
RADIX built-in function 428 
RAISE2 built-in function 429 
RANDOM built-in function 429 
RANGE option 142 
READ statement 243 
REAL attribute 32 
REAL built-in function 429 
REAL pseudovariable 430 
recognition of names 128 
RECORD attribute 233 
RECORD condition 322 
record-oriented data transmission 242 
definition of 228 
statements 243 
RECSIZE environment characteristic 235 
recursion, effect on automatic variables 101 
RECURSIVE option 100 
recursive procedures 100 
REDUCIBLE option (abbr: RED) 125 
REENTRANT option 125 
REFER option 210 
on AREA attribute 212 
reference 
locator 206 
references 50 
regional data set 230 
REGIONAL(1) environment.characteristic 235 
relative data sets 229 
relative line 283 
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RELEASE statement 103 
restrictions 102 
REM built-in function 430 
remote format item 282 
REORDER option 125 
REPEAT built-in function 430 
REPEAT option 175 
repetition factor 
picture 286 
strings 40 
repetitive execution (DO statement) 174, 179 
replacing macro facility variables 451 
REPLY option 172, 173 
RESCAN option 454 
RESERVED 138 
RESIGNAL statement 309 
restoring language-specified defaults 144 
restricted expressions 68 
restricted integer 219 
restrictions on FETCH and RELEASE 102 
data conversion 85 
results of arithmetic operations 56 
RETCODE option 125 
RETURN statement 99, 121 
REVERSE built-in function 431 
REVERT statement 308 
REWRITE statement 244 
RIGHT built-in function 431 
ROUND built-in function 432 


S 


S picture character 296 
SAMEKEY built-in function 433 
scalar data, definition of 24 
SCALARVARYING environment characteristic 235 
SCALARVARYING option 242 
scale 31 
SCALE built-in function 433 
scaling factor 32 
scaling factor character 299 
scan, macro facility 450 

control statements 451 

statements 450 
scope 132 

of condition prefix 304 

of declaration 132 

of established action 306 
SEARCH built-in function 433 
SEARCHR built-in function 434 
SELECT statement 193 
select-groups 193 
self-defining data (REFER option) 210 
semicolon 15 
SEQL (SEQUENTIAL) attribute 234 
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SEQUENTIAL attribute (abbr: SEQL) 234 
SET 
option of data transmission statements 248 
SET option 208 
ALLOCATE statement 208 
LOCATE statement 245 
READ statement 243 
sets, data 228 
See also data sets 
SIGN built-in function 435 
SIGNAL statement 309 
signalling a condition 309 
SIGNED attribute 33 
SIGNED built-in function 435 
signs 296, 298 
simple statements 18 
SIN built-in function 435 
SIND built-in function 436 
single-byte character set (SBCS) 10 
single-byte statement elements (SBCS) 
statement elements 14 
SINH built-in function 436 
SIZE built-in function 436 


SIZE condition 323 


SIZE condition prefix 303 
SKIP format item 283 
SKIP option 257 
SKIP statement 195 
SNAP 305 
source-to-target conversion rules 
bit 83 
character 81 
coded arithmetic 77 
fixed binary 78 
fixed decimal 78 
float binary 79 


flAat Aaanional 7Or 
HVAL USUINIA) 1g 
graphic 84 


numeric character PICTURE 80 
spacing format item 284 
special characters 12 
specification characters 286 
SQRT built-in function 437 
stacking 101 
standards 6 
statement elements 14 

DBCS 20 
statements 167 

See also PARM 

See also statez 

*PROCESS 191 

%INCLUDE 187 

%NOPRINT 188 

%NOTE 188 

%PAGE 190 

%POP 190 


statements (continued) 
%PRINT 190 
%PROCESS 191 
%PUSH 191 
%SKIP 195 
assignment 18, 167 
BEGIN 111 
CALL 120 
CLOSE 239 
coding recommendations 17 
compound 18 
DECLARE 129 
DEFAULT 142 
DELAY 172 
DELETE 245 
DISPLAY 172 
DO 173 
END 183 
FETCH 103 
FORMAT 267 
FREE 202 
GET 
data-directed 261 
edit-directed 265 
list-directed 268 
STREAM input 253 
GET STRING 253 
GOTO 184 
group 19 
IF 185 
ITERATE 187 
keyword 18 
LEAVE 187 
LOCATE 245 
null 18, 189 
ON 305 
OPEN 236 
PACKAGE 92 
PRINT 190 
PROCEDURE 94 
PROCESS 191 
PUSH 191 
PUT 
data-directed 262 
edit-directed 266 
list-directed 269 
STREAM output 253 
READ 243 
RELEASE 103 
RESIGNAL 309 
RETURN 99, 121 
REVERT 308 
REWRITE 244 
SELECT 193 
SIGNAL 309 
simple 18 


statements (continued) 
SKIP 195 
STOP 195 
syntax, general 17 
WRITE 244 
% statements 
%ACTIVATE 453 
%assignment 454 
%DEACTIVATE 454 
%DECLARE 455 
%DO 455 
%END 456 
%GOTO 456 
%IF 456 
%INCLUDE 457 
%null 458 
static allocation 198 
STATIC attribute 199 
with INITIAL attribute 223 
static storage 198, 199 
STG (STORAGE) built-in function 438 
STOP statement 195 
storage 
allocation 198 
automatic 200 
classification 198 
connected 217 
control 198 
controlled 201 
nonconnected 147 
static 199 
STORAGE built-in function (abbr: STG) 438 
STORAGE condition 324 
storage control built-in functions 379 
ADDR 383 
ALLOCATION 384 
BINARYVALUE 387 
CURRENTSIZE 394 
CURRENTSTORAGE 395 
EMPTY 398 
ENTRYADDR- 399 
NULL 416 
OFFSET 416 
OFFSETADD 417 
OFFSETDIFF 417 
OFFSETSUBTRACT 417 
OFFSETVALUE 418 
POINTER 425 
POINTERADD 426 
POINTERDIFF 426 
POINTERSUBTRACT 427 
POINTERVALUE 427 
SIZE 436 
STORAGE 438 
STREAM attribute 233 
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stream-oriented data transmission 252 
definition of 228 
list directed 252 
STRG (STRINGRANGE) condition 324 
STRING built-in function 438 
string data 
arithmetic graphic 43 
attributes 28, 29 
bit 41 
BIT attribute 37 
CHARACTER attribute 37 
character data 39 
definition 25 
graphic 42 
GRAPHIC attribute 37 
mixed 42 
NONVARYING attribute 38 
PICTURE attribute 38 
repetition factor 40 
transmission of varying length 242 
using quotation marks with 25 
VARYING attribute 38 
string operator (|) 15 
STRING option 257 
GET statement 253 
PUT statement 253 
string overlay defining 218 
STRING pseudovariable 439 
string-handling built-in functions 380 
BIT 387 
BOOL 387 
CHAR 390 
COPY 392 
GRAPHIC 403 
HIGH 406 
INDEX 407 
LEFT 409 
LENGTH 409 
LOW 411 
MAXLENGTH 413 
MPSTR 415 
REPEAT 430 
REVERSE 431 
RIGHT 431 
SEARCH 433 
SEARCHR 434 
SUBSTR 439 
TRANSLATE 442 
TRIM 443 
VERIFY 447 
VERIFYR 448 
STRINGRANGE condition (abbr: STRG) 219, 324 
STRINGRANGE condition prefix 303 
STRINGSIZE condition (abbr: STRZ) 325, 219 
STRINGSIZE condition prefix 303 
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structure mapping 154 
effect of UNALIGNED attribute 157 
example of 157 
rules for mapping one pair 156 
rules for order of pairing 156 
structures 
assignment 168 
attributes 30 
controlled 203 
cross sections of arrays of 154 
declaration of 147 
definition of 147, 149 
expression 51 
highest level number 148, 149 
levels 147, 149 
LIKE attribute 151 
maximum number of levels 148, 149 
names 147, 149 
qualification 150 
specifying organization of 147 
variable 151 
STRZ (STRINGSIZE) condition 325 
subfields 289 
SUBRG (SUBSCRIPTRANGE) condition 219, 326 
subroutines 94, 104, 120, 381 
See also bisr 
See also built-in subroutines 
definition 104 
definition of 371 
returning from 121 
subscripted qualified reference 153 
SUBSCRIPTRANGE condition (abbr: SUBRG) 219, 
326 
SUBSCRIPTRANGE condition prefix 303 
subscripts 
definition of 146 
interiéaved 154 
of arrays 146 
SUBSTR built-in function 439 
SUBSTR pseudovariable 440 
SUBTRACT built-in function 440 
SUCC built-in function 440 
SUM built-in function 441 
suppression characters 291 
symbols, composite 13 
syntax of data-directed data 260 
SYSPARM macro facility built-in function 461 
SYSTEM macro facility built-in function 462 
SYSTEM option of ON statement 305 
SYSVERSION macro facility built-in function 462 


T 


TAN built-in function 441 
TAND built-in function 441 


TANH built-in function 442 
targets 52 
array, requirements for 168 
intermediate results 53 
pseudovariables 52 
requirements for target variables 168 
structure, requirements for 168 
variables 52 
termination 
begin block 111 
block 92, 183 
procedure 99 
program 90 
THEN clause of %IF statement 456 
THEN clause of IF statement 185 
TIME built-in function 442 
TINY built-in function 442 
TITLE specification in OPEN statement 236 
TO option 175 
TRANSLATE built-in function 442 
TRANSMIT condition 326 
TRIM built-in function 443 
TRUNC built-in function 444 
type 3 do-group 255 


U 


UFL (UNDERFLOW) condition 328 
UNALIGNED attribute 139 

effect on structure mapping 157 
UNBUF (UNBUFFERED) attribute 234 
UNBUFFERED attribute (abbr: UNBUF) 234 
unconnected storage 147 
UNDEFINEDFILE condition (abbr: UNDF) 327 
UNDERFLOW condition (abbr: UFL) 328 
UNDERFLOW condition prefix 303 
UNDF (UNDEFINEDFILE) condition 327 
UNION attribute 149 
unions 

attribute 30 

cross sections of arrays of 154 

declaration 149 

levels 149 

qualification 150 
UNSIGNED attribute 33 
UNSIGNED built-in function 444 
UNSPEC built-in function 445 
UNSPEC pseudovariable 446 
UNTIL option 174, 176 
UPDATE attribute 233 


V 


V picture specification character 290 
VALID built-in function 447 


VALUE attribute 45 
VAR (VARYING) attribute 38 
VARIABLE attribute 48 
variables 

array 144 

controlled 201 

definition 24 

entry 113 

reference 24 

Structure 147 
VARYING attribute (abbr: VAR) 38 
VERIFY built-in function 447 
VERIFYR built-in function 448 
VSAM environment characteristic 235 


W 


WHEN option of GENERIC declaration 118 
WHEN option of SELECT statement 193 
WHILE option 174, 176 

WINPROC option 126 

WRITE statement 244 


X 


X (hex) character string constant 40 
X picture specification character 287 
X-format item 284 

XN (binary hex) constant 34 


Y 


Y zero replacement picture character 298 


Z 


Z (null-terminated) character string constant 40 
Z zero suppression picture character 291 

ZDIV (ZERODIVIDE) condition 329 

zero replacement character 298 

zero suppression characters 291 

ZERODIVIDE condition (abbr: ZDIV) 329 
ZERODIVIDE condition prefix 303 
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